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PREFACE 


MANUAL OBJECTIVES 


The RSX-11M/M-PLUS System Management Guide documents system programs 
and ~~ procedures that test, monitor, maintain, and customize 
RSX-11M/M-PLUS operating systems after system generation. 


INTENDED AUDIENCE 


This manual is intended for system managers, operators, and system 
programmers who perform system management functions. The manual is 
not intended for general users or applications programmers. 


STRUCTURE OF THIS MANUAL 


The RSX-11M/M-PLUS System Management Guide consists of 19 chapters and 
two appendixes as follows: 


Chapter 1 summarizes each program and procedure described in Chapters 
2 through 19. 


Chapter 2 describes how you use the Account File Maintenance Program 
(ACNT) to create and maintain accounts on multiuser protection 
systems. 


Chapter 3 describes how you use the Console Logger to control I/0 to 
the console output device (C0): and record system messages at a 
terminal and/or in a log file. 


Chapter 4 describes how you use the I/O Exerciser (IOX) to detect and 
diagnose I/0 problems on the disk, terminal, and tape units in your 
system's hardware configuration. 


Chapter 5 describes how the Bad Block Replacement Control Task (RCT) 
performs bad block handling and recovery on Mass Storage Control 
Protocol (MSCP) devices such as the RA80. 


Chapter 6 describes how you use the Resource Monitoring Display (RMD) 


to display information about the active tasks in your operating system 
and the availability of system resources. 


Chapter 7 describes how to set up the Queue Manager for convenient 
multistream line-printer spooling. 


For RSX-11M-PLUS. systems only, this chapter describes how you set up 


batch processors that enable you to direct a — sequence to the 
operating system at a predetermined time of day. 
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Chapter 8 describes how you use the SHUTUP Program to shut down the 
system in an orderly fashion. 


Chapter 9 describes how you use the Data Terminal Emulator (DTE) to 
log in from a local Micro/RSX system to an external computer system 
and conduct an interactive session. 


Chapter 10 describes how you use the Virtual Monitor Console Routine 
(VMR) to alter a system image file on disk. 


Chapter 11 describes command line interpreter tasks, including how to 
write them and how to use new Executive directives in them. 


Chapter 12 describes how to task build and install the DCL task with 
various options. It also describes the Macro Meta language, which is 
a set of macros that describes the mapping from DCL syntax to MCR 
syntax. With this language, you can alter or add commands to extend 
DCL. 


Chapter 13 describes the Pool Monitoring Support that controls the use 
of the system's dynamic storage region (pool). 


Chapter 14 describes the Shuffler, which is a task that compacts 
memory space in system-controlled partitions. 


Chapter 15 describes how you use the RSX-lLIM-PLUS reconfiguration 
services (CON and HRC) to reconfigure system resources to isolate the 
system from the effects of faulty hardware elements. 


Chapter 16 describes RSX-11M-PLUS I/O Queve Optimization, which 
improves the throughput of the disk subsystems used in your system. 


Chapter 17 describes RSX-11M-PLUS Resource Accounting, which creates a 
transaction file of system usage information. 


Chapter 18 describes RSX-11M-PLUS Shadow Recording, which allows your 
System to back up all information being written to a Files-1ll disk. 


Chapter 19 describes RSX-11M-PLUS and Micro/RSX Disk Data Caching, a 
feature that enhances 1/0 operations by reducing the number of 
physical 1/0 requests performed during a disk operation. 


Appendix A describes the Serial Despooler, which is superseded by the 
Queue Manager to handle line-printer spooling for most systems. 


Appendix B describes the set of User File Directory (UFD) conventions 
observed by the operating system for files on disk. A section of file 
naming conventions is also included. 


ASSOCIATED MANUALS 


Before you read this manual, you should be familiar with the 
RSX-11M/M-PLUS MCR Operations Manual, the RSX-11M/M-PLUS Utilities 
Manual, and, for DIGITAL Command Language users, the RSX-11M Command 
Language Manual or RSX-11M-PLUS Command Language Manual. Although you 

o not need to read the RSX-11M System Generation and Installation 
Guide or the RSX-11M-PLUS System Generation and Installation Guide 


use of the programs and procedures documented in this manual. 
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CONVENTIONS USED IN THIS MANUAL 


Convention 


red ink 


blue ink 


lowercase 


UPPERCASE 


{optional ] 


shading 


CTRL/a 


Meaning 


Designates user input. Responses from 
programs are designated in black ink. 


Designates RSX-11M-PLUS multiprocessor system 
information. 


A horizontal ellipsis indicates that the 
command line element immediately preceding 
the ellipsis can be repeated one or more 
times. 


A vertical ellipsis indicates that part of a 
command sequence or program output continues 
but is not relevant to the discussion of the 
example. 


In a command line, lowercase words and 
letters indicate that you substitute a value. 
Usually, the lowercase word describes’ the 
value to be substituted. 


Command elements other than those shown in 
lowercase for which you substitute a value 
are always uppercase. Within descriptions, 
these command elements are never truncated. 
In examples, they may be truncated according 
to the rules of the particular program. 


A reverse number is a white number printed in 
a black circle. These numbers key a part of 
an example to the text that explains that 
part of the example. The reverse number 
appears both in the example and the 
explanation. 


Square brackets indicate that the enclosed 
item is optional. 


Shaded portions of text describe only one 
operating system. 


Gray shading indicates that the text applies 
only to RSX-1IM-PLUS operating systems. 
Shading is not used in chapters that describe 
programs that are unique to Pee es 


Red shading indicates that the - text applies” 
only to RSX-11M operating systems. se 


Portions of text that are not shaded describe 
both operating systems, except in the 
RSX-11M-PLUS-only chapters. 


The symbol _ Glia) indicates that you press a 


key while simultaneously pressing and holding 
down the CTRL key; for example, CTRL/C, 
CTRL/O. © 
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SUMMARY OF TECHNICAL CHANGES 


The programs and procedures described in this manual have all _ been 
enhanced to include new software features. The following lists 
descriptions of new software and the enhancements to previously 
existing software for RSX-11M Version 4.2 and RSX-11M-PLUS Version 
aa 0% 


Account File Maintenance Program (ACNT) 


On RSX-LIM-PLUS systems, passwords are now automatically encrypted 
when they are created. Passwords can now be up to 39 characters long. 


I/O Exerciser (IOX) 


Support for exercising terminals has been added. This is accomplished 
by using the LOOPBACK parameter to the SELECT command. 


Resource Monitoring Display (RMD) 
Two new displays about cache regions have been added: the RMD C page, 


which displays general statistics about a cache region; and the RMD D 
page, which displays detailed statistics about a cached device. 


SHUTUP Program 


Messages now include a “reason for shutdown" field on RSX-LIM-PLUS 
systems. 


Virtual Monitor Console Routine (VMR) 
The VMR chapter includes the following changes: 
e New Introduction. 
e New Table of Commands. 
e Revised section describing how.to start VMR. 
e Additional information about the FIX-IN-MEMORY command _ which 
describes fixing tasks on RSX-11S systems with memory 
Management (PLAS) support. Also, information has been added 


which describes fixing tasks on RSX-11M and RSX-11S systems 
above 124K-words. 
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e Information has been added to the NOTES section of the INSTALL 
command which describes (on RSX-11M and RSX-11M-PLUS systems) 
what happens to changes made in a common when a common is 
removed and then reinstalled. New information has also been 
added which describes restrictions for using the INSTALL 
command to install device commons that were created with the 
SET/PAR command. 


New INSTALL command examples have been added. 


e A NOTE has been added to the LOAD command indicating that you 
can load drivers above the 124K-word limit on RSX-11M systems. 


@e More information and new restrictions have been added to the 
REDIRECT command, which describes redirecting I/O requests 
from one physical device to another. 


@ New NOTES have been added to the REMOVE command describing (on 
RSX-11M and RSX-11M-PLUS systems) what happens to changes made 
in a common when a common is removed and then reinstalled. 
Also, another new NOTE has’ been added which indicates (on 
RSX-11M-PLUS systems) that a region cannot be removed if there 
are tasks installed in the system that reference that region. 

e The description of the RUN command has been totally revised. 
New RUN command examples have been added. 


e The SAVE command supports the following new devices: 


Also, a NOTE to the SAVE command has more information about 
saving a system on paper tape. 


e New SET command examples have been added. 


New VMR Keywords 


The following VMR commands have new keywords: 


ASSIGN 
es /SYSTEM (RSX-11M-PLUS systems only.) 
Defines, displays or deletes 
system-wide logical device 
assignments. 
INSTALL 


/WB (RSX-11M-PLUS systems only.) 
Specifies where a read/write 
common will be checkpointed to. 


/EMAP (RSX-1LIM-PLUS systems only.) 
Informs the system that the task 
will use the fast-mapping 
feature of the Executive. 
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/AVO 


/BLKMOD 


/DEC 


/EDIT 


/HSYNC 


/PARITY 


/PASTHRU 


/PRINTER PORT 


/REGIS 


/SOFT [=ttnn: ] 


/TTSYNC 


Xviii 


(Full-duplex terminal driver 
only.) Informs the system that 
the specified VT100-series 
terminal has the advanced video 
option. 


(Full-duplex terminal driver 
only.) Enables local editing and 
block-mode transmission for’ the 
specified terminal. 


(Full-duplex terminal driver 
only.) Indicates that the 
specified terminal is upwardly 
compatible with the VT100-series 
of terminals. 


(Full-duplex terminal driver 
only.) Informs the system that 
the specified terminal can 
perform ANSI-defined advanced 
editing functions. 


(Full-duplex terminal driver 
only.) Enables host-terminal 
synchronization, which controls 
the typeahead buffer to prevent 
it from overflowing. 


Enables parity generation and 
checking. 


(Full-duplex terminal driver 
only.) Instructs the system to 
ignore the original function of 
special characters typed at the 
specified terminal and to 
instead pass them to a program 
in their binary form. 


(Full-duplex terminal driver 
only.) Informs the system that 
the specified terminal has a 
printer port. 


(Full-duplex terminal driver 
only.) Informs the system that 
the specified terminal supports 
the ReGIS graphics set. 


(Full-duplex terminal driver 
only.) Informs the system that 
the specified terminal can 
accept software-defined 
character sets. 


(Full-duplex terminal driver 
only.) Enables the terminal 
synchronization option for the 
specified terminal. 


SUMMARY OF TECHNICAL CHANGES 


Modified VMR Keywords 


The following VMR command keywords have new information: 


INSTALL 


SET 


/CLI 


Indicates that the task being installed is a Command Line 
Interpreter (CLI). 


/XHR 


Use the /XHR keyword when installing tasks with external headers. 


/BUF 


The buffer size for a terminal must be greater than or -equal_ to 
14 (decimal). 


/POOLSIZE 


If you do not specify a value (on RSX-11M-PLUS systems), VMR also 
displays the lowest physical address at which a partition can 
start (32-word blocks). 


/REMOTE 
The terminal has a line to the following additional multiplexers: 


DHU11 
DHV11 
DLV11 
DZQ11 
DZV11l 


You can specify several different answer speeds for the following 
variable-speed multiplexers: 


DHU11 
DHV11 
DZQ11 
DZV11 


You cannot specify an answer speed for a DL1l or DLV11 
multiplexer. 


/SPEED 
You can specify additional speeds for the following multiplexers: 


DH11 
DHU11 
DHV11 
DZ11 
DZV11l 
DZQ11 


If you have a DZ11, DZQ11, or DZV11 multiplexer, the receive and 


transmit speeds must be the same because these multiplexers do 
not support split speeds. 
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/TERM 
The SET/TERM command supports the following additional terminal 
types: 

DTCOl1 LA50 LQP02 

LNO3 LA210 LQPO3 

PC 3XX VT2XX 


New VMR Error Messages 


VMR has new error messages that pertain to bus’ switches, shared 
regions, LOAD/CTB keyword, fast mapping, and pool space. 


Disk Data Caching 
RSX-1LIM-~PLUS and Micro/RSX now include support for disk data caching. 


Disk data caching enhances 1/0 operation by reducing the number of 
physical I/O requests performed during a disk operation. 


XxX 


CHAPTER 1 


INTRODUCTION 


This chapter summarizes the functions of the programs and procedures 


documented in the chapters of this manual. Each chapter is summarized 
in the order in which it is presented in the manual. 


Chapter 2 - Account File Maintenance Program (ACNT) 


The Account File Maintenance Program (ACNT) allows a privileged user 
to create and maintain an account file on multiuser protection 
systems. Each account entry consists of information such as an 


account number (the user's UIC) and password, the default device 
(SY:), the user's first and last name, and the default command 


language interpreter (CLI). ACNT allows a privileged user to create 
an account file, add and delete accounts, modify accounts, list the 
accounts, examine an individual account, and sort the account entries. 


The chapter describes, with examples, how to use each ACNT function. 


Chapter 3 - Console Logger 


The Console Logger consists of a driver (CODRV) and a task (COT...) 
that handle I/0 to the console output device (CO:) and record 
time-stamped system messages on a terminal and/or ina log file. You 
use MCR SET commands from a privileged terminal to start and stop 
console logging, disable the log file or the console terminal, and 
reassign the log file and console terminal. You select Console Logger 
Support during SYSGEN. 


The chapter documents the console logging commands and presents an 
extensive terminal session with explanations of the commands used in 
the session. 


Chapter 4 - I/O Exerciser (IOX) 


The I/O Exerciser (I0X) detects and diagnoses I/O problems on_ the 
disk, tape, and terminal units in your system's hardware 
configuration. IOX exercises Files-1ll disks, non-file-structured 
disks, magnetic tapes, DECtapes, and cassettes. IOX performs three 
kinds of exercises. The IOX Command Language enables you to_ specify 
and control the exercise for the units in your system. You choose an 
exercise appropriate to a unit and set exercise parameters. that 
determine how the unit is exercised. 


The chapter documents each IOX command in alphabetical order and 
provides examples that explain how to set parameters for the three 
kinds of IOX exercises. 
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Chapter 5 - Bad Block Replacement Control Task (RCT) 


The Bad Block Replacement Control Task (RCT) handles bad _ block 
replacement and recovery on Mass Storage Control Protocol (MSCP) disks 
such as the RA80. Bad block handling on MSCP disks consists of four 
stages: detecting, notifying, replacing, and revectoring. The disk 
controller (UDA50) detects bad blocks and notifies the driver (DUDRV). 
The driver activates RCT. RCT performs the bad block replacement 


functions that enable the controller to revector (redirect) I/O from 
the bad block to the replacement block. 


RCT also performs replacement and recovery on MSCP disks that went off 
line during bad block replacement or before the contents of a 
write-back cache were copied to the disk. 


The chapter describes bad block replacement functions and recovery 
techniques. 


Chapter 6 - Resource Monitoring Display (RMD) 


The Resource Monitoring Display (RMD) provides information about the 
active tasks in your operating system and the availability of system 
resources. This information includes the active tasks, their location 
in memory, the amount of memory they occupy, and the available pool 
space. RMD generates dynamic displays on CRTs and "snapshot" displays 
on hardcopy terminals. 


There are three displays: memory, active task, and task header. 
There is also a help page that tells you how to switch display pages. 
Each display page has a setup page from which you can alter the 
contents of the associated display page. You can access any RMD 
display and alter the contents of the display from the MCR command 
line. 


On RSX-11M~PLUS systems, a system statistics display and error log 
count display are also available. a 


The chapter contains an example and explanation of the memory display. 


Chapter 7 - Setting Up and Running the Queue Manager (QMG) 


The Queue Manager (QMG) has the primary function of controlling the 
system's line printers and the print jobs that are passed to them. 
Users can specify the number of copies they want printed, the time the 
job is to be released for printing, whether the file is to be deleted 
after printing, and which printer they want to use. Users can display 
all information about the QMG queues and can alter the characteristics 
of jobs in queues. Some installations may have user-written output 
processors that pass jobs to devices other than line printers. The 
nonprivileged functions of QMG are documented in the RSX-11M/M-PLUS 
Batch and Queue Operations Manual. ee ee 


This chapter documents the privileged system management functions of 
QMG. Systems can have as many as 16 output queues (including the 
default PRINT queue) and 16 output processors. Print processors’ can 
be initialized to print a specified number of flag pages before each 
print job, to accept or reject print jobs specifying that lowercase 
printing is required, and to handle many kinds of printed forms. 


INTRODUCTION 


On _RSX-11M-PLUS systems, OMG also supports batch processing. 


_RSX-11M-PLUS © systems can have as. many as 16 batch queues and 16 batch 
processors. 


The chapter includes an illustrated explanation for setting up the 
Queue Manager. 


Chapter 8 - The SHUTUP Program 


The SHUTUP program allows a privileged user to shut down the system in 
an orderly fashion. SHUTUP prompts for the number of minutes to wait 
before shutdown, the number of minutes between shutdown messages, and 
the number of minutes to wait before disabling logins. Before halting 
the system, SHUTUP performs cleanup functions such as logging out all 
logged-in terminals, submitting the user-written command file 
LB: [{1,2]SHUTUP.CMD to Indirect for execution, stopping the Queue 
Manager, Console Logger, and Error Logger (if present), deallocating 
checkpoint space, and dismounting mounted devices. 


The chapter provides an example and explanation of SHUTUP output. 


Chapter 9 - Terminal Emulation and File Operations with Other Systems 


A local Micro/RSX terminal can log in to and conduct an interactive 
session with an external computer system. This session is established 
using the Data Terminal Emulator (DTE). The external system can be an 
RSX-11M or RSX-11M-PLUS system, a Professional Personal Computer, or 
another Micro/RSX system. Once a local Micro/RSX terminal is logged 
in to an external system, the external system becomes the host system. 
The host system views Micro/RSX as_ remote. During an interactive 
session, files can be transferred between the host system and 
Micro/RSX. Files are transferred using the Micro/RSX File Transfer 
Utility. 


The chapter describes how to perform terminal emulation and file 
operations between a Micro/RSX system and an external system, with 
examples. 


Chapter 10 - Virtual Monitor Console Routine (VMR) 


The Virtual Monitor Console Routine (VMR) is a task that contains a 
Subset of the Monitor Console Routine (MCR) commands. You use VMR to 
make the same changes to the system image file on disk that you would 
make to the running system with MCR. Some of these changes are 
setting the size of pool, creating partitions, loading drivers, and 
installing tasks. The advantage of using VMR is that you can almost 
completely configure a system image file before you bootstrap it. 


The chapter presents each of the VMR commands in alphabetical order. 


Chapter 11 - Command Language Interpreters 


A command line interpreter, or CLI, is a task that services 
unsolicited commands meant for the Operate hake or an application. 
These commands are not prompted for by any task nor are they given to 
a task by a read operation on a terminal. A CLI is also an efficient 
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means of interfacing an application command processor to any number of 
terminals, because no read QIO or character AST processing is 
involved. 


This chapter introduces the concepts of CLIS on RSX-11M/M-PLUS 
systems. The chapter includes enough information to allow the 
programmer to write application-specific CLIs. 


Chapter 12 - The DCL Task 


The DIGITAL Command Language (DCL) is a general purpose command 
language syntax implemented on several DIGITAL operating systems. 


This chapter explains the ways in which DCL can be installed on _ your 
system and documents the means by which the DCL task parses and 
translates commands. In addition, this chapter documents the Macro 
Meta Language, a set of MACRO-1l macros used to define DCL. An 
experienced programmer can add commands to DCL or remove them, or 
alter DCL by changing parts of DCL, such as altering defaults or 
eliminating qualifiers. 


Chapter 13 - Pool Monitoring Support 


Pool monitoring support controls the use of the system's dynamic 
storage region (pool). This support monitors pool levels, restricts 
use of pool, and notifies you when pool is near depletion. This 
support consists of two parts: the RSX-11M/M-PLUS Executive pool 
monitor code and the privileged Pool Monitor Task (PMT). 


The chapter describes how to get pool monitoring support, the 
conditions that affect PMT, PMT defaults, and how to abort PMT. There 
is also an annotated example of PMT output for extreme fragmentation. 


Chapter 14 - Shuffler Support 


The Shuffler (SHF) is a privileged task that compacts space in 
system-controlled partitions when a memory allocation failure occurs. 
The Shuffler operates only within system-controlled partitions. 


The chapter describes Shuffler structure, Shuffler interaction with 
the operating system, ways to monitor the Shuffler, and Shuffler 
algorithms for the operating system. 


Chapter 15 - RSX-1IM-PLUS Reconfiguration Services 


The reconfiguration services consist of two tasks (CON and HRC) and a 
driver (RD:). With these services, you can alter or display 
information about various system resources such as devices and memory. 
The main purpose of the reconfiguration services is to allow you to 
isolate faulty hardware so that it does not affect the system 
adversely. 


The chapter describes the functions of CON, RD:, and HRC. The 
reconfiguration commands are described, with examples of how to use 
each one. The chapter also gives procedures for recovering from 
various hardware errors. 
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tem. This is done by making 
2 requests in the queue for a 
Meee ee ety dian device, ree methods of optimization are ic onda 
Nearest Cylinder, Elevator, and Cylinder ‘Scan. 


The chapter describes each of the: three methods — et optimization and 
how to choose the one that is best for your system. There is also a 
sae of error mer eeoes ato @ the SET /OPT command - ee aS 


“chapter 17 _ RSX-11M-PLUS Resource Accounting 


Resource Accounting - provides a transaction fie of system — 
information. Information is gatherea on each user in a system and on 
total system utilization. This information can be used to. bill 
individual users for the resources. used and for measuring overall 
system performance. By analyzing the data in the transaction file, 
you can determine such things as who used the system, for how long, 
how much CPU time they used, and a number of other statistics. For 
system utilization, you can find out the number of users, number of 
logins, how much input/output was done, and other system usage 
information. The information in the transaction file can be displayed 
or you can write a Beegran cess th ile and analyze the data. 


The chapter describes how Re 


, kecountiog works and contains an 
exanpie of a transaction = ee a 


Chapter 18 - RSX-11M-PLUS | 


ba k up all information as it 

_ It does so by creating two 
More than one pair of disks 
pairs cannot overlap. The first 
the original disk that exists 
, You can make any disk on 
e primary disk of a shadowed 


“Shadow Recording allows you 
is being written to a 
identical disks called a “gt 
may be shadowed, but sha 
disk of the pair, the prim. 
whether or not Shadow Rec 
your system, anicadaineng the 
pair. 


The dee prepare your oveten for 
it, and how to control it. The Shadow Recording commands and error 
messages are described in detail. 


Chapter 19 ~- _RSX-11M-PLUS and Micro/RSX Disk Data Caching» 


“Disk data eedhing is a feature on RSX-11M-PLUS. and Micro/RSX systems 
that enhances 1/0 operations by reducing the number of Phyeiae)) 1 
-_Fequests performed during a disk operation. 


In addition to monitoring all 1/0 operations performed on  glek 
devices, disk data caching decreases the number of physical 1/0 
operations taking place on "cached" disk drives by using a cache 
Partition in memory. Copies of disk data are placed in the cache 
partition, making the data available for memory-to-memory transfers 
instead of disk-to-memory transfers ducing an 1/0 request. 


The chapter describes all of the disk data caching features. You can 
disable, override, modify, and monitor disk data caching. 
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Appendix A - Serial Despooler (PRT) 


The Serial Despooler Task (PRT...) provides a means of eliminating 
contention for the system line printer. Rather than waiting for the 
line printer to become available, the task directs the output intended 
for the line printer to a disk file. 


This appendix briefly describes the Serial Despooler Task and 
documents Task Builder information for it. 


Appendix B - RSX-11M/M-PLUS UFD CONVENTIONS 


The RSX-11M and RSX-11M-PLUS operating systems observe a set of User 
File Directory (UFD) conventions for files on disk. These conventions 
provide a uniform and consistent method of locating, allocating, and 
maintaining a file on disk. 


This appendix describes group and member numbers and their use in 
identifying the contents of system UFDs. A section on file-naming 
conventions is also included. 
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THE ACCOUNT FILE MAINTENANCE PROGRAM (ACNT) 


RSX-11M and RSX-11M-PLUS each provide an Account File Maintenance 
Program (ACNT) for creating and maintaining an account file ona 
multiuser system. The account file contains entries for all User 
Identification Codes (UICs) authorized within the multiuser protection 
system. One UIC can have several users, each user having his or her 
password. When you try to log in, the system checks the HELLO or 
LOGIN command parameters against the account file to determine whether 
or not the user should have access to the system. 


With Version 3.0 of RSX-11M-PLUS, passwords are automatically 
encrypted when a new account is created. Once a password is 
encrypted, the password cannot be seen. Therefore, if you forget your 
password, you must get a privileged user to enter the ACNT program to 
obtain a new password. ee Rh 


NOTE 
Please be aware that no new user-written encryption 
routines will be supported after Version 3.0. 
However, encryption routines written prior to Version 
3.0 will continue to be supported. 
If you wish to change your password, you must use the SET PASSWORD 
command to do so. You have to know your old password if you want to 
use the SET PASSWORD command. If you do not remember your old 
password, then a privileged user can run ACNT and obtain a new 
password for you. Each account in the account file contains’ the 
following information: 
@ UIC (the account number) 
@ Password 
@e User's default system device 
e User's default file protection 
e First name 


@e Last name 


@ User's Command Line Interpreter (CLI) if the system has 
multi-CLI support 


@ Date and time of the user's most recent login 


@ The number of times that the user has logged in to the system 
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@e Whether the user's terminal is to be slaved after login 
@ On RSX-11M-PLUS systems, a session identifier 


@ On RSX-1IM-PLUS systems, the user account number 


2-1 INVOKING ACNT 
Invoke ACNT, from a privileged terminal, as follows: 
2“RUN $ACNT GED 


ACNT identifies itself and displays a list of options after you type 
the RUN command. 


A nonprivileged user can use ACNT only to modify the account entry for 
his or her password. (See the RSX-11M/M-PLUS MCR Operations Manual). 


On RSX-11M-PLUS systems, a nonprivileged user cannot use ACNT to 
modify the account entry for his or her password. If a nonprivileged 
user attempts to run the ACNT program, ACNT will print the following 
message: 


ACNT -- Cannot te tun from @& mon-rrivilesed terminal 
Use SET FASSWORDT to chensge sour rassword 


2.2 ACNT OPTIONS 


ACNT is an interactive program that allows privileged users’ the 
following options: 


e (C) Create an account file 

e (A) Add accounts to the file 

e (E) Examine individual account entries in the file 

e (M) Modify individual account entries in the file 

e (L) List account entries in the file 

e (D) Delete account entries from the file 

e (S) Sort the account entries in the file 

e (CTRL/Z) Exit from ACNT 
ACNT prompts you for an option. Enter one of the letters indicated in 
the parentheses above. The program responds by requesting further 
input or by displaying information for the option you selected. The 


remainder of this chapter discusses the ACNT options and includes 
examples of each. 
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2.2.1 Creating the Account File 


The Create option lets you create the account file. Create the 
account file immediately after generating your system to allow normal 
use of the system. The Create option allocates the account file 
(LB:[0,0JRSX11.SYS) and sets the file protection so that only 
privileged users and privileged tasks can access the account file. 


You may copy and optionally extend the account file using the 
Peripheral Interchange Program (PIP) (see the RSX-11M/M-PLUS Utilities 
Manual). The new copy will have the default file protection, 
therefore, immediately run _ ACNT. ACNT will detect the incorrect 
protection codes and restore proper protection. 


The following example shows how to create the account file on RSX-11M 
systems. After you invoke ACNT, it responds with a list of options 
and a prompt, as follows: 

Oetions eres A - Alt, CO - CREATE FILE, 0 ~ DELETE: EF - EXAMINE > 

Ce RSet = AOULE Ys & - SORT CTRL 2 = bRIT 

Enter ortion? ¢ 

Enter maximum mumber of accounts! 35. Qe 
Enter a decimal number (n.) to specify the maximum number of account 
entries to be listed in the file. The system then creates an account 
file (LB:[0,0]RSX11.SYS) large enough to contain 35 accounts. 


When the Create operation is complete, press the ESCAPE key to request 
a list of options. Then you can add accounts to the account file. 


2.2.2 Adding Account Entries 


The Add option lets you add accounts to the account file. ACNT 
prompts you for the following: 


e UIC (the account number). 

@e Password. 

e User's default system device. 

@e User's default file protection. 
@ First name. 


@e Last name. 


e User's CLI. If your system does not have multi-CLI support, 
ACNT does not prompt you for the user's CLI (MCR is the 
default). 


@e Whether the user's terminal is to be slaved after login. 
@ On RSX-11M-PLUS systems, a session identifier. 
@ On RSX-11M-PLUS systems, a user account number. 


ACNT maintains the file in ascending order by UIC. 
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The prompts for the password, first name, and last name specify the 
maximum number of characters that ACNT accepts. Passwords can be up 
to 39 characters long, but be aware that systems using DECnet can only 
use 8-character passwords. The legal characters for user names and 
passwords are as follows: 


@ A through Z, upper- and lowercase 


@ oO through 9 


e ' (apostrophe) 
e . (period) 
e - (hyphen) 


e $ (dollar sign) 
e ! (exclamation point) 


The default system device prompt requests a device name and unit 
number (optional if 0). ACNT accepts logical, physical, and pseudo 
device names. The acceptance of logical and pseudo device names lets 
you move the user disk to another drive without having to change the 
default device in the account file. When specifying the device name, 
do not include a colon (:). 


RSX-11M-PLUS systems include two additional prompts: one is for a 
session identifier and the other is for the user account number. The 
session identifier and user account number are optionally used by the 
Resource Accounting Program (see Chapter 17). The session identifier 
is also used by the HELLO progr as (see the RSX-11M/M-PLUS MCR 


Operations Manual). 


The following example shows bei slag add entries to the account file on 
RSX-11M systems: 


Ortions aret A - ADTs C ~- CREATE FILE, G - DELETEs E - EXAMINE, 
L ~- LIST» M ~ MODIFY» S ~- SORT» CTRIL/Z - EXIT 

Enter ortiont & G&D 

Enter account or <ESC> for ortions ¢( NeN >? 5°15 Ge 

Passward € #=39 charse >)? ALBSCS GA 

Lefault ssustem device ( [DU 03 DR Ge 

First mame ( <=12 chars. )$ JANE GE 

Lest name ( {£214 chars. )% BARRETT Ge 

Refeult file wratection ( CSY¥sOWsGRrWOT )3 RWEDyRWEDYRWEDR GED 
Enter user CLI Cdefault=MCR)? DCL Ge 

Slave terminal? COVY/NID? N RED 

UFD DBLIECOOSr015T4 


In this example, ACNT creates an account in the account file for Jane 
Barrett. Jane's password is A1B2C3 and her default system device is 
DBO:. Her default file protection is read, write, extend, and delete 
access for system, owner, and group; the world has read-only access. 
(This is also the system default protection.) Jane's CLI is DCL, and 
her terminal is not slaved after login. 


ACNT remains in Add mode until you press the ESCAPE key to request a 
list of options. 
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The _ following example ‘sho 


count to an RSX-11M-PLUS 


account Utility optic 


Add —— Add an 

Delete — Delete 2 
Exemine Examine ‘emisting Scecust 

List List sccount file 


Modife account file. 
Sort account file - 

ere Terminate utility session 
option! A GED 
account ~ Carouey. aceteri) 10110 ra 
1t sustem device ¢( BRU )t nue GED : 

rd 39 chars. or fewer)! BASEKITPL ca 
or fewer)? Kathleen a 
(14 che or fever): Bean Ge 3 
le Protection (CSV 2OW,GReWOI) CRWED RED: *R1] GED oe 
: : tring (C¢rour, member] or Enamel)? KATHLEEN @ 
or eeversk ee ee a 


Lo poi 


Kathy Bean. Kathy's 
CNT when the. account is 
ead, write, extend, and 
ly access for group and 
ust be 9 characters or 
tem device ais DUO:. Her 
is 23, her CLI is DCL 
terminal is not. slaved. 


— this ecspple. ‘ACNT c 
one, 2 ee KITPL, 


Poh 


Her ‘default dive 
is KATHLEEN, a 


ae finished 
n, the system returns the 


atlas i Hee aceon tae 
prompting for all the 
Aol ene Mepeeset 


a Aer oun entry. co: dire peated, 
2.2.3 Examining Account Entries 
The Examine option displays two lines of detailed information for each 


account in the account file on RSX-11M systems. The first line 
contains, from left to right, the following information: 


e vUIC 

@ Password 

e First name 
e Last name 


e User's default system device 
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The second line contains the following information: 
@e Date of the last login. 
e@ Time of the last login. 
@ Number of times the ieex has logged in to the system. 


@e User's CLI. If your system does not have multi-CLI support, 
ACNT displays the default CLI (MCR). 


Whether the user's terminal is to be slaved after login. 


ACNT remains in Examine mode until you press the ESCAPE key to request 
a list of options. 


The following example shows y information for an account 
on an RSX-1 1M-PLUS Syehene os 


RSX- 11M- PLUS acco g ir nance Program 


Account Utility. options 
Add as an 
Iielete 
Examine — 
Modify. unit file 
Sort. es aoe account file pes 
CIRLAZ Terminate Meslay session 

Enter ortion! E GD 

aes account Carours- siehher) ! 10°10 GE ; es 
-~AUG-85 OBf3OI02 RSX- L1M- PLUS Multiuser Account File List Pade 1 


Ae cs 2 CO10010] Logindefaults = adidas elae tp 
Lreme = BEAN : «Frame = KATHY Fassword = CFNCRYPTED) 
nertht DOL  Seseion ID = KLH Account = 23 


Totellodins = 2.  Lastlogin = 24-AUG-85 12:44:92 
Characteristics = NOS lave Defdirstring = 
Derrrptectiay * CBWE DeRME eR Ht 


In this example, Kathy Bean's account is examined. The first line of 
the display lists her UIC [010,010] and her login defaults (her 
default system device is DUO: and her default directory string is 
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[KATHY]). The next line of the display lists her last name, first 
name, and, in the password field, (ENCRYPTED) is displayed. If any of 
the passwords in any accounts that are being examined are encrypted, 
the password field will display (ENCRYPTED) instead of the password 
itself. The third line displays Kathy's CLI (DCL), her session 
identifier (KLM), and her account number (23). Next, her total number 
of logins and last login are displayed. The fifth line of the display 
shows Kathy's terminal characteristics (her terminal is set to 
noslave) and her default directory string is left blank, because it is 
also her login default, which is shown in the first line of the 
display. The last line of the display shows Kathy's default file 
protection. . 


After examining an account, or a group of accounts, ACNT prompts you 
with the following message: j 


Key <RETURN: to continues CTRL/Z for ACNT ortions menut 


2.2.4 Modifying Account Entries 


The Modify option allows you to change the password, default system 
device, default file protection, first name, and last name for an 
account, and the slave/no-slave status of a terminal. You can change 
the CLI of an account if your system includes the multi-CLI option. 


In an RSX-LIM-PLUS system, the Modify option also allows you to change 
the session identifier and the account number. 


After you specify the account to be modified, the program displays an 
account entry and asks’ for verification. Type either Y (Yes) or N 
(No) to indicate that the correct account was or was not’ specified. 
If you specify N, ACNT searches the file for another entry with the 
same UIC. When you enter a Y, ACNT prompts for the entry details. 
Press the ESCAPE key if you do not want to change an item. 


The following example shows how to modify account information on an 
RSX-11M system: 


Orebions egret A ~- Alift,s C - CREATE FILE: f - DBELETE+s EF - EXAMINE» 

Leo LIST ee - MODTEY ss. S - SORT: CTRL/Z = EXTT 

Enter ortion? ™ @ED 

Enter account or <ESC> for arptions ¢( NeN 2? Sri? GED 

CEOO5201277. BARB BARBARA SPENCER NEO? 
OS/G8/B81 15t0et 11 OH0006 MCR N 

This antery P ELY/NVIE ¥ 

Tueee ESOS to leave entre un 

Feseword € <=39 chars. 33 

Hefault sustem device ¢ DN 

First name ¢ <s12 chars. »% €9 

Last mame ¢ “214 chars. 3% €80 

Enter user CLI Cdefeult=MOR)? DCL @eD 

Slave terminal? CLY/NI1? €s0 


7e & ot 


In this example, Barbara Spencer's account is modified. Her password 
(BARB) is changed to BES, and her CLI (MCR) is changed to DCL. ACNT 
remains in Modify mode until you press the ESCAPE key to request a 
list of options. 
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The following example shows how to modi fy account information on an 
RSX~-11M-PLUS system: 


RSX-1LIM-FLUS Account File Maintenance Frogram 


Account ULilits ortions are 


Add Add am account to file 
Nelete Telete em account file entrs 
Examine Examine existing account 
List List account file 

Mochi fs Modify account file 

Sort Sort account file 

CTRI/Z Terminate utility session 


Enter ortian’ M QED 
Enter account (rouse, member)? 10716 


Owner = CO10010] Losgindefaults = TUOOITKATHYI 

Loame = BEAN Fname = KATHY Fassword = (ENCRYPTED) 
TerfChyT = ECL Sesston ID = KLH Account = 23 
Totallogins = 2 Lastlodin = 24-AUG-85 12344322 
Characteristics = NOSlave Defdirstring = 


LefProtectian = [TRWETsRWEDs Re RI 
This entrs PF COY/NTT: Y GED 

THee <“ESC> to leave entre uncnhansed 
Fagsword (39 chars. or fewerd$ ESC 
fefauib susteam device ¢ Tt 9% €89 
First mame (12 chars. or fewer 33 €8¢ 
Lat mane ¢€14 chars. or fewer 2! €80 
Trafeult fale erobection (fSYr+OW»sGReWOI); €§c 
Tefault cireetory strinae KATHLEEN 

New directors hes heen created 

Enter user CLT (default=OCbL)t €9 

Slave terminal? CLY/NITT: €50 

Tincaehle login/logout messages? CY/NI! €0 
Suscion identifler (2 charge. or fewer) TRKK 
Account tomber 4 didgits or fewer)? €§C 


In this example, Kathy Bean's account is modified. Her default 
directory string is changed to KATHLEEN, and her session identifier is 
changed to KKK. 


When she changed her default directory string, the system printed the 
message: : 


ew direclores hes been creatends 


After ACNT has prompted you for changes to all the account fields, it 
prompts you with the following message: 


Kee TRE TURN: to continues COTEL/?7 for ACNT oFftioans menus 


2.2.5 Listing Account Entries 


The List option either displays on the user's terminal or spools to 
the line printer all account entries in the account file or a 
specified group of entries. If you specify the line printer, ACNT 
creates the file ACCNT.DMP. This file contains the account 
information you specified. ACNT prints the file if the spooler is 
installed in your system. If the spooler is not installed, you may 
print ACCNT.DMP after you exit from ACNT. 
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The following example shows how to list account entries on an 
RSX-11M-PLUS system: : a 


RSX~-11M-FLUS Account File Maintenance Program 


Account Utility ortions are? 


Add Add an account to file 
Lelete Delete an eccount file entry 
Examine — Kamine existind account 
List List eccount file 

Modify Modify account file 

Sort Sort account file 

CTRL /Z Terminate utility session 


Enter option’ |. @éD 

Onle the old UMENCRYPTED tyre rasswords can be rrinted 
Print passwords (default mod)? CY/NI]3 RED 

ALL accounts (default nod? CY/NI7$ 

List on Terminal(default) or FileCACCOUNT. DMP) CYT/FI$ Ge 


If any of the passwords are encrypted, the password field will display 
(ENCRYPTED) instead of displaying the password itself. 


After all the accounts you have specified have been listed, ACNT 
returns the following prompt: 


Key <RETURN> to continuer CTRL/Z for ALNT ortions menut 


On RSX-11M systems, this option lists accounts in the same manner. 
However, RSX-11M systems do not support password encryption. When the 
list operation is complete, ACNT displays its options and prompts’ for 
a choice. 


2.2.6 Deleting Account Entries 


The Delete option eliminates individual accounts from the file. After 
you specify the account to be deleted, ACNT displays the account entry 
and requests a Y (Yes) or N (No) response for verification. If the 
response is N, ACNT searches for another account with the same UIC. 
If the response is Y, ACNT asks if you want to delete the account's 
UFD and other files. Another Y response deletes these files. If you 
enter N in response to the deletion query, the account's files and UFD 
are left intact. 


The following example shows how to delete accounts from the account 
file on an RSX-11M system: 


Qetions egret A ~- AlMs ( - CREATE FILE» It - DFLETF» F - EXAMINE? 

lL. - LIST» M - MODIFY: S - SORT, CTRL/Z - EXIT 

Enter ortion’s D RED 

Enter account or <ESC> for ortions € N»eN 93 Sel? GED 

COOOSs01277 MLK MAUREEN KACZKA WELLS 
08/06/85 08:46251 06004 TCL N 

This entre P CELY/NTV2 Y GED 

Yelete UFD and files? CCY/NI]73 Y @ED 

PIF NRLIEC OOS, O12 TIKES K/DE 

SPIP TRIS ECOs G1 1005012  NIRFK/TE 


In this example, ACNT deletes Maureen Kaczka's UFD and files. 
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The following example shows how to delete accounts from the account 
file on an RSX-11M-PLUS system. 
RSX-LIM-PLUS Account File Maintenance Frogram 


Account Utility ortions ere: 


Add Add an aceount to file 
lelete Yelete gen account file entrs 
Examine Examine existing eccount 
List List account file 

Modify Modify account file 

Gort Sart egccount file 

CTRL #Z Terminate utility session 


Enter ortion?t tO GED 
Enter eccount (srour, member)?! 1010 RED 


Qwnier = £O100107 Logindefaults = RUOOtTKATHYI 

Loame = BEAN Fname = KATHY Password = CENCRYPTED) 
NefCr Io = DCL Session IT = KLH Account = 29 
Totallioging = 3 Lastiogin = 24-AUG-85 12744322 


Mharacteristies = NOSlave fefdirstring = 
NefFrotection = CRWET+RWEDs Re RI 

This emtrs? ECYSNT? ¥ 

Yelete UFT and files? EY/NTE Y ED 
Account enters hes bean deleted 


In this example, ACNT deletes Kathy Bean's account and files. 


2.2.7 Sorting Account Entries 


The Sort option sorts the account entries in ascending order by UIC. 
The following example shows how to sort the account file on an RSX-11M 
system: 


+ 


Qe Lions are? A ~- Alt, Cf - CREATE FILE» fT - NFLETE+ £F ~ EXAMINE s 
Lo o~ LIST, 4 - MODTEY, S - SORT, CTRLYZ - EXIT 
Enter option! S  (QEet 


When the sort operation is complete, ACNT displays all its options and 
prompts for a choice. 


The following example shows how to sort the account file on 
RSX-11M-PLUS systems: 


RSX-DiMe PLUS Account File Maintenance FProsram 


Account Ubilits ofrtions are? 


Acct Arid an secounmt to file 
felete Telete ar asceount file entry 
Examine Ex@mine @xisbind gecount 
List Light account file 

Modif: Modify aeecount file 

Sart Sork goeount Tile 

CTRL AZ Terminale utility sessian 


Enter oftaians  S  @ReD 


After the sort operation is complete, ACNT returns the following 
message and then redisplays the ACNT menu: 


Accor File is mow sorted by UIC 
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2.2.8 Exiting from ACNT 


The Exit option allows you to exit from the ACNT program. The 
following example shows how to exit from ACNT on RSX-11M systems: 


Qetiang are? A ~- ANDs C - CREATE FILE, I - THELETE» E& - EXAMINE» 


ke = LEST Mo MODTEYs So - SORT: CTRL/Z - EXIT 
Enter oe tiont 


When you exit from ACNT, ACNT displays the following message 
terminal: 


OPERATTON COMPLETE 


on your 


The following example shows how to exit from ACNT on RSX-11M-PLUS 


systems: 
RSS-LIM-FLUS Account File Meintenance Frosram 


Account Utility oetions are? 


And Add an account to file 
TYelete Relete an eceount file entry 
Examine Examine @xreting gceount 
List List eeccournt file 

Modify Modify aecount file 

Sark Sork agccount file 

CTRL 7Z Termingts utility session 


Enter ortian?} 
When you exit from ACNT, ACNT returns the following message: 


Accounk file moacification is comrlete 


2.3 ERROR MESSAGES 
The ACNT program returns the following error messages: 


ACNT -- Account already exists 


Explanation: You attempted to add an account with a UIC and 


password that already exists in the account file. 
ACNT -- Account file already exists 


Explanation: You attempted to create an account 
already exists. 


ACNT -- Account file error 


Explanation: The program detected an I/O error 


processing the account file. 


ACNT -- Account file full 


file that 


while 


Explanation: The account file is full; you cannot add 
further accounts. See the description of the Create option 


for details on how to enlarge the account file. 


ACNT -- Cannot find account 


Explanation: You attempted to delete, examine, or modify an 


account that does not exist. 


ACNT 


ACNT 


ACNT 


ACNT 


ACNT 


ACNT 


ACNT 
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-- Invalid default device name 


Explanation: The default system device specified is not a 
directory device. 


-- Warning ** Device does not exist on current system. OK? 


[Y/N]: 


Explanation: The specified default device is not in the 
system. If you enter Y, ACNT retains the device name as a 
logical device name. ACNT prompts again for the device name 
if you enter N. 


-- Invalid option 

Explanation: In response to the Enter option: prompt, you 
did not specify A, cC, D, E, L, M, S, or CTRL/Z, which 
represent valid ACNT options. 

-- Listing file error 

Explanation: When you use the List option, ACNT opens’ the 
file Sy:[current uic]JACCNT.DMP. This message indicates that 
ACNT cannot open the file; for example, the device is full 
or it does not contain a UFD for the current UIC. If the 
device is full, delete some files. Create a new UFD if 
there is no UFD for the current UIC. 


-- Syntax or command input error 


Explanation: You typed an invalid character. Enter the 
correct data. 


-- Workfile - dyn. mem. exhausted 

Explanation: There is insufficient dynamic memory. Install 
the task in a larger partition, or install it with a larger 
increment. 


-- Workfile - virtual storage exceeded 


Explanation: The workfile exceeds virtual memory. 


CHAPTER 3 


THE CONSOLE LOGGER 


The Console Logger consists of a driver (CODRV) and a task (COT...) 
which together control I/O to the console output device (CO:) and 
record time-stamped system messages on a terminal, ina log file, or 
both. You select support for console logging during system 
generation. 


For RSX-11M systems, console logging is available only on mapped 
systems. 


3.1 THE CONSOLE OUTPUT DEVICE (CO:) 


Your system has a console output device (CO:) and a console terminal. 
When the Console Logger is active, I/O to CO: is controlled by the 
console output task (COT...) and the console driver (CODRV). When the 
Console Logger is not active, CO: is a pseudo device, and I/O to CO: 
is controlled by the terminal driver. In both cases, output to CO: 
can be forwarded to a terminal that you assign as the console 
terminal. 


3.1.1 CO: as a Pseudo Device 


As mentioned in the previous section, CO: is a pseudo device when the 
Console Logger is not active. You can redirect CO: to any terminal 
on your system using the MCR REDIRECT command. The terminal driver 
controls all I/O to CO: that is redirected to the console terminal. 


3.1.2 CO: with the Console Logger Active 


When the Console Logger is active, the console driver (CODRV) and the 
console output task (COT...) control all I/O to CO:. You use a 
console logging command to assign the console terminal (see Section 
3.4.5) rather than redirecting CO: by means of the MCR REDIRECT 
command. 


There are two advantages to using the console logger to control I/O to 
CO:. These are as follows: 


1. Console logging allows you to record messages sent to CO: in 
a log file. You can record messages on the console terminal, 
in the log file, or both. This flexibility enables you to 
inspect the log file at any time and to free a terminal when 
you do not need an on-line display of console logging. 
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2. The console logger time-stamps messages to CO: that have not 
been time-stamped by the task issuing the message in the 
following form: 

hh:mm:ss hours, minutes, and seconds. 


Also, prior to outputting the first message after a change of 
date, the Console Logger outputs the current time and date. 


3.2 INSTALLING COT... AND LOADING CODRV 

If you select console logging at system generation time, SYSGEN 
installs the console output task (COT...) and loads the console driver 
(CODRV) by including the appropriate commands in SYSVMR.CMD. You only 
need to install COT... and load CODRV if one of the following 
conditions exists: 


1. You have removed one or both of them and want to restore 
console logging. 


2. You have altered SYSVMR.CMD to eliminate them. 


3.3 COMMUNICATING WITH THE CONSOLE LOGGER 


You can use MCR commands to communicate with the Console Logger. 
Tasks use the CODRV driver to communicate with the Console Logger. 


3.3.1 User Communication with the Console Logger 


COT... is a privileged task. From a privileged terminal, you issue 
console logging commands to start and stop console logging, assign the 
console terminal, and specify the console log file. Table 3-1 
summarizes the console logging commands. There are no DCL equivalents 
for the console logging commands. Section 3.4 discusses each console 
logging command in detail. These commands are processed by the 
COT... task. 


3.3.2 Task Communication with the Console Logger 


Tasks communicate with the console driver (CODRV) by issuing QIOs. 
CODRV handles QIOs to CO: for reading, writing, attaching, and 
detaching. All other I/O functions to CO: are passed to the terminal 
driver as if they were issued directly to the console terminal. 


3.3.2.1 Writing to CO: - Tasks can issue QIOs to print system 
messages on the console terminal or write system messages in the 
console log file. For example, HELLO issues a QIO to print a message 
to the console terminal each time a user logs in to the system. 


Messages to CO: may begin with a CTRL/G to ensure that COT... sends 
the message to the most recently assigned console terminal, even if 
you have disabled the console terminal by specifying the NOCOTERM 
option (discussed in Section 3.4.4). 
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The buffer in COT... accepts messages not longer than 256(10) bytes. 
Note that using the MCR SET/BUFFERSIZE command to set the buffersize 
of device CO: does not affect this restriction.) 


Table 3-1 
Summary of Console Logging Commands 


MCR Command Meaning 


SET /COLOG Displays the current 
console terminal and 
logfile assignments 


SET /COLOG=ON Starts console logging 

SET /COLOG=OFF Stops console logging 

SET /COLOG/NOC[OTERM] Disables the console 
terminal 

SET /COLOG/COTCERM][=TTnn: ] Enables the console 


terminal or changes the 
console terminal assignment 


SET /COLOG/NOLOGFILE Disables the logfile 
SET /COLOG/LOG[FILE][=[ filespec]] Enables the console logfile 
or changes the logfile 
assignment 
3.3.2.2 Reading from CO: - Tasks can issue QIOs to read input from 
the console terminal. For example, an operator can use the console 
terminal to respond to prompts by a system task that require user 
input. COT... does not record messages in the log file that are read 


from the console terminal. 


3.3.2.3 Attaching and Detaching CO: - Tasks may attach to CO:; 
however, the attach is a NOP. Though tasks may attach or detach CO: 
they are not allowed exclusive access to CO:. 


3.4 CONSOLE LOGGING COMMAND DESCRIPTIONS 

You use console logging commands to perform the following functions: 
e Display the current console terminal and log file assignments 
e Start and stop console logging 
@e Change the console terminal and log file assignments 


e Disable the console terminal or the log file 
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The general format of console logging commands in MCR is as follows: 


>SET /COLOG[L[MCRoption]]... 


where: 

SET The MCR SET command 

COLOG Console logging keyword 

MCRoption One of the console logging functions. You can truncate 


these options to three letters. 


3.4.1 Displaying the Current Console Terminal and Log File 
Assignments 


To display the current console terminal and log file assignments, type 
the following: 


-SET /COLOG 


Use this option to determine if the Console Logger is active. When 
the Console Logger is active, COT... displays the current console 
terminal and/or log file assignments. For example: 


-SET /COLOG 

COT ~~ 

Console = TTOOO! 

Losfile = TROOOTECLs4710GONSOLE.LOGEL 


If the Console Logger is not active, the display option indicates the 
following: 


COT -- 
Console = None 
Logfile = None 


3.4.2 Starting Console Logging 
The following command line starts console logging: 

“SET /COLOG=0N 
When you start console logging, COT... retains the current console 
terminal assignment. If you have just bootstrapped the system, 
COT... assigns CO: to TTO:. The default location and name of the log 


file is LB:[{1,4]CONSOLE.LOG. COT... always creates a new version of 
the default log file when you start console logging. 


3.4.3 Stopping Console Logging 
The following command line stops console logging: 
“SET /COLOG=OFF 


When you stop console logging, the current console terminal assignment 
is retained. Use the MCR DEV command to display the current console 
terminal. Section 3.5 discusses how you can use the MCR DEV command 
to monitor how CO: is redirected. 
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NOTE 


Do not abort COT.... Aborting COT... causes severe 
pool fragmentation. 


3.4.4 Disabling the Console Terminal 
To disable the console terminal, type the following command: 

'SET “COLOG/NOCCCOTERMI 
This command line enables you to maintain a log file of system 
messages without using a terminal as the console terminal. This is 
especially useful if your system does not have many terminals or if 
you cannot spare a terminal to dedicate to receiving system messages. 
When you do this, messages starting with a bell still come out on the 
console terminal (i.e., Device not ready). To completely disable CO: 
(that is, to stop these messages) assign CO: to NL:. 


Once you have disabled the console terminal with the NOCOTERM option, 
the following command: 


=SET /COLOG/COTERM 


restores the most recent console terminal assignment. 


3.4.5 Reassigning the Console Terminal 
The following command line reassigns the console terminal: 
SSE T /COLOG/COTLECERMIICO=T Prints 2 
where TTnn: is the newly assigned console terminal. When you 
bootstrap your system, the default console terminal assignment is 


TTO:. When you start console logging, the default console terminal 
assignment is the current console terminal. 


3.4.6 Disabling the Log File 
To disable the log file, type the following command line: 
SSET /COLOG/NOLOGFILE 
This command line enables you to continue recording system messages 


time-stamped by COT... at the console terminal without recording the 
messages in a log file. 


3.4.7 Reassigning the Log File 
The following command line reassigns the log file: 


2SET /COLOG/LOGCOCFILEIC=Cfilesreci]] 


where "filespec" is any legal file specification as described in the 
RSX-11M/M-PLUS Utilities Manual. The default file specification is 


LB:[1,4]CONSOLE. LOG. 
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To change only part of the file specification for the log file, type 
only that part of the file specification after the equal sign that you 
want to change from the default. For example, if LB: is DRO: and 
you want to make the log file DBO:[301,55]CONSOLE.LOG, type the 
following: 

SET /COLOG/LOGFILE=DBOIL301°557 


If you want to make the log file TESTLOG.LOG in the default UIC on 
LB:, type the following: 


SSET /COLOG/LOGFILE=TESTLOG 
In all cases, COT fills in the missing parts of the file specification 
with parts from the default file specification, LB:[1,4]CONSOLE.LOG, 
and creates a new version of the log file. 
To create a new version of the current log file, type the following: 
eSET /COLOG/LOGF ILE 
If you have disabled the log file with the NOLOGFILE option, this 
command line restores the most recent log file assignment. Although a 
new version cf the log file is created, the rest of the file 
specification does not change. 
To change the log file back to the default, type the following: 
"SET “COLOG/LOGFILE 


This command line creates and opens a new version of the default log 
file. 


3.4.8 Using Multiple Console Logging Commands 
You can enter multiple console logging commands in a command line. 
The following command line: starts console logging, assigns the 
console terminal to TT17:, and opens a log file named TESTLOG.TST in 
the default UFD on LB: 

SSET /COLOG=ON/COTERM=TTI7¢/. OGFILE=TESTLOG. TST 


The following command line disables the console terminal and restores 
the log file to the default: 


SET /COLOG/NOCOTERM/LOGF ILE 


3.5 MONITORING THE STATUS OF CO: 


To use the MCR DEV command to determine the status of CO:, while the 
console logger is active, enter the following: 


SQEV COs 
The system responds as follows: 
COO? LOATED 


This response means that the console driver (CODRV) is loaded and that 
COT.., handles system messages to CO:. 
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Use the console logging display option to display the console terminal 
assignment as follows: 


“SET /COLOG 


If you have disabled console logging, use the MCR DEV command to 
determine the terminal assigned as CO: as follows: 


POEM lis 

COO? TTrns 
where nn is the terminal to which the CO: pseudo device is 
redirected. 
Before COT... exits, it redirects CO: to the current console 
terminal. If there is no console terminal (because you disabled it 
with the NOCOTERM option) when you stopped console logging, then CO: 
is redirected to the last terminal COT... assigned as the console 
terminal. In this case, the terminal driver handles messages directed 


to CO: and redirects them to TTnn:. 


If you have disabled the console terminal with the NOCOTERM option but 
continue to record system messages to CO: ina log file, then use the 
MCR DEV command to determine the status of CO: 


SEY C04 
COO? LOATET 


This response means that the console driver is loaded and that 
COT... handles all messages directed to CO:; however, system messages 
are not directed to a terminal. Use the display option to verify that 
CO: is not assigned to a terminal. 


3.6 REDIRECTING CO: 

Use the MCR REDIRECT command to redirect CO: to a terminal, only when 
the console logger is not active. If you try to redirect CO: while 
the console logger is active, you will receive the following error 
message: 


-RET -- Device mot redirectable 


For example, if the Console Logger is active, the console terminal is 


assigned to fTT2:, and you stop console logging, COT... redirects CO: 
to TT2: before exiting. Use the MCR DEV command to verify that CO: 
is redirected to TT2:. To assign the console terminal to TTO:, use 


the MCR REDIRECT command as follows: 
* RET TTOt=CO3 


If you then start console logging again, COT... will assign TTO: as 
the console terminal. 


NOTE 


Do not redirect CO: to CO:. 
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3.7 READING THE LOG FILE 
Because the current log file is open for writing if LOGFILE is 
enabled, you can read it only by using PIP with the Shared Read (/SR) 
switch. For example, if the log file is DRO:[1,4]JCONSOLE.LOG, and you 
type the following: 

SPIPF TIS =nRO?CCL»47ICONSOLE.! OG 


PIP responds as follows: 


FIF -- Oren failure an inreut file 
DROSCLi*s4ICONSOLE.LOGs1 -- Accessed for write 


To read the log file, type the following: 
SFTP TIi=QRO°CE 1,4 71 CONSOLE. LOG/SR 
A sample log file follows: 


4243719 Logout user [194] TTSS33 


146%43°35 Losin user ALPHA [793341 TT53? 
14845207 Login user BRAVO C7»4?] TTis: 
T4244¢21 KKK TMG -- dismount comrlete 

14¢746732 Losin user TECNET [2492240] TT30s 
14247392 Losin user CHARLIE T7373 TT22t 


LS6347338 KKK LEO? -- mat ready 
14(°47°49 Lodout user [1°41 TTS33 
LS3472785 Logout user [72373] TT223 


1463482601 Login user ALPHA LJia34) Tass 
14349340 Login user DECNET £24092407 HTOS 


3.8 SAMPLE CONSOLE LOGGING TERMINAL SESSION 


Following is an annotated example which shows a console logging 
terminal session illustrating how you use all the commands described 
in the Sections 3.4 through 3.7. 


Example 3-1 Sample Console Logging Terminal Session 


(This example assumes that LB: is assigned to DBO:.) 


“SET “COLOG 

COT -- 

Canealea = None 

Logfile = None 

NEY COG 

COO: TTO? 

“SET /COLOG=0N 

SQEY C3 

COOs LOADED 

SSET “COLOG 

C 0 T woes 

Console = TT9O03 

Logfile = DBOOOGICCL» 47] CONSOLE.LOGs1 
SSET /COLOG/COTERM=TTS1! 

SSET /COLOG/LOGFILE=DRICCSO.,ASIITEST 


eo0.60UDllC DCO 


(continued on next page) 
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Example 3-1 (Cont.) 


“SET /COLaG 
COT 
Console = TTOS1:3 

Logfile = TROOOSLLSOL,SSITITEST.LOGs 1 
=SET /COLOG/NOCOT 

“SET /COLOG 

COT 
Console = 
Logfile = 
“TEY COE 
COO? LOATIET 

*SET /COLOG/COTER/NOLOG 
=SET /COL OG 

COT 

Console = TTOSL: 

Logfile None} 

SSET /COLOG/COTFERM=TTL?? /LOG= 

“SET /COLOG 

COT 

Console = TTGL7$ 

Logfile = TROOOTELE SOL»sSSIITEST.LOGI 2 
SSET /COLOG=0FF 

SSEYT /COLOG 

COT 
Consale = 
Woefale 
“TEV COS 
COGt TTL?) 
2RET TTSLi=C0% 

SEV A 

COG? “isis 

2SET /COLOG=ON/L_LOG=DRBLILE7s 30173 
“SET /COLOG 

Guy == 

Console = TTOS13 

Lodfile = DBOOLICO 7» 3017 1C0ONSOLE.LOG 
SSET /OENLOG/COT=TTOL/LOG 

-SET /COLUGG 

Console = TTOO03 

Lodfile QRGOOSEC1L+42 ICONSOLE. LOG) 2 
SPIP YOS=LBtlc ts 47 700ONSOLE. LOG 

ee Geen Pailure on ineut file 
DBOS LCA, 447 7CONSOLE.LOGs3 
PIF TLt=L Biol is 421 CONSOLE.VLOG/SR 
LSt43t19 Losout user [019417] TIS3S? 
16343235 Losin user ALFHA 
146845297 Losin user BRAVO 
L62462321 KKK TMOG 
163446232 login user 
16247322 Login user 
164347:38 x*xKK LFOt 
16247249 Losout user 
16347358 Logout user 
146¢46201 Losin user ALPHA 
16249249 odin user TECNET 

SSET /COLOG/NOCOTERM/NOL OG 

COT Not Lostsins on a terminal 
SDEY CG3 

COG? TTO3 


None 
DROOOLCLSZOL»SSIAITEST.LOG? 1 


None 
Nore 


DECNET 
CHARL TE 
not ready 
CLiv,4dl TSS; 
L027 937373 


or 


ii 


Accessed for 


write 


8) 


CO?» S34) TTS3s 


CkK7 4277 
dismount camelete 


MPLS 


PES4O,240]] TT30: 
LEY ys 734.4 


Ries 


TT22 3 


A eee i a 
CO240»2401] HTO$ 


to 


3 


file, 


COT 


exiting 


eae 


Sample Console Logging Terminal Session 
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Displays the current console terminal (none) and log file 
(none) assignments, indicating that the Console Logger is 
not active. 


Illustrates the MCR DEV command that shows how CO: is 
redirected. CO: is redirected to TTO:, which means that 
the Console Logger is not active and that the terminal 
driver redirects CO: to TTO:. 


Starts console logging. 

Shows that the Console Logger is active because CODRV is 
loaded. The display option shows that COT... redirects CO: 
to TTO: and that DBO:[1,4]JCONSOLE.LOG;1 is the log file. 
These are both the defaults when you bootstrap your system. 


Shows how you assign the console terminal to TT5l1:. 


Shows how you assign the log file to DR:[{301,55]TEST.LOG. 


COT... fills in the missing parts of the file specification 
with parts from the default file specification. In this 
case, COT... supplies the file type. 


Displays the current console terminal (TT51:) and log file 
(DR:[301,55]JTEST.LOG;1) assignments resulting from command 
lines 5 and 6. 


Disables the console terminal and retains the current log 
file (DR:({301,55]TEST.LOG;1). The display option confirms 
this. 


Shows that when you disable the console terminal with the 
NOCOTERM option, the console logger is still active (CODRV 
is loaded), but CO: is not redirected to any terminal. 


Illustrates the multiple commands that restore the most 
recent console terminal assignment (TT51:) and disable the 
log file. The display option confirms this. 


Illustrates the multiple commands that assign the console 
terminal to MTT17: and restore the most recent log file. 
The display option confirms these assignments. The version 
number of the log file is incremented. 


Stops console logging. The display option confirms that the 
console logger is not active. CO: is redirected to TT17:, 
which was the last console terminal assignment before 
COT... exited. 


Redirects CO: to TT5l: with the MCR REDIRECT command and 
confirms this with the MCR DEV command. 


Illustrates multiple commands on a command line. Starts 
console logging, retaining the current console terminal 
assignment (TT5l1:) redirected with the MCR REDIRECT command 
in step 13, and opening a log file 


DB001:[7,301 JCONSOLE.LOG;1. The display option confirms 
these assignments. 


Illustrates multiple commands on a command line. Assigns 
the console terminal to TTO: and restores the default log 
file. The display option confirms these assignments. The 


version number of the log file is incremented. 
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Illustrates what happens when you try to read an open log 
file without the Shared Read switch (/SR). 


Shows how to read an open log file using the Shared Read 
switch. Each message in the log file begins with a time 
stamp. 


® Disables the console terminal and the log file. 
COT... exits because no console logging is in progress. 
COT... displays a message informing you that it is exiting. 
The MCR DEV command shows that CO: is redirected to TTO:, 
the console terminal assignment before COT... exited. 


3.9 ERROR MESSAGES 
COT -- LUN assignment to console terminal failed 


Explanation: You specified an incorrect terminal number as_ the 
console terminal. 


User Action: Use the COTERM option to assign the console 
terminal to a terminal in your hardware configuration. 


COT -- Illegal console terminal 


Explanation: You tried to assign a device that is off line or is 
not a terminal to CO:. 


On RSX-11M-PLUS eee the ies es be illegal because it is 
a spooled terminal. oe 


User Action: Use the COTERM option to assign a terminal in your 
hardware configuration to CO: 


COT -- Console driver not loaded, COT exiting 
Explanation: The console driver, CODRV, is not loaded. 


User Action: Load the console driver and start console logging. 


COT -- Maximum consecutive write errors, disabling logfile 
Explanation: An error occurred on five consecutive write 
operations to the log file. COT... closes the log file and 


disables logging to the log file. 


User Action: Determine the problem that caused the write errors 
and correct it. Then restart COT... 


COT -- Not logging on a terminal or to a file, COT exiting 


Explanation: You have disabled the console terminal with the 
NOCOTERM option and the log file with the NOLOGFILE option. 


User Action: If you did not intend to stop console logging, 
start it again specifying either a log file, console terminal, or 
both. 
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COT -- Unable to redirect CO: to a terminal - CO: is offline, COT exiting 
Explanation: CO: is off line. There is a problem with the most 
recent console terminal assignment. It may be off line or not a 
terminal. 


On RSX-11M-PLUS systems, the problem may be that a spooled 
terminal was assigned. : a : 


User Action: Start COT... and specify a legal console terminal 
with the COTERM option. Then, stop console logging. 


COT -- Syntax error 


Explanation: You made an error in entering a console logging 
command. 


User Action: Check the command description in Section 3.4, and 
enter the command correctly. 


COT -- Will attempt console LUN assignment to TTnn: 

Explanation: This error message may occur when you stop- console 
logging. If COT... cannot redirect the console terminal to the 
terminal currently assigned as the console terminal, it tries to 
redirect CO: to the previous console terminal assignment. If 
that fails, it tries TTO:. If that fails, it generates the error 
message: 

SCOT -- LUN assignment to console terminal failed 


User Action: Start console logging again, specifying a legal 
console terminal. Then stop console logging. 


COT -- Illegal command - Console logging has not been turned on 


Explanation: You issued a console logging command before 
starting console logging. 


User Action: Start console logging and issue the command. 


COT -- Logfile x error 
filespec -- QIO Error Code -nn. 
Explanation: An I/O error occurred while COT... was performing 


an operation on the log file. The function being performed, x, 
is WRITE, OPEN, or CLOSE. The filespec is any legal filespec 
designated for the log file. The error code, -nn., is an I/O 
error code. 


User Action: Look up the I/O Error Code in the RSX-11M/M-PLUS 
and Micro/RSX I/O Operations Reference Manual and take the 
appropriate action. 


CHAPTER 4 


THE I/O EXERCISER (I0X) 


The I/O Exerciser (IOX) detects and diagnoses I/O problems on the 
disk, terminal, and tape units in your hardware configuration. Using 
the IOX Command Language, you can execute, control, and monitor I/0 
exercises on device units that you specify for exercising. 


This chapter has a narrative part and a reference part. The narrative 
part presents the information you need to run the I/O Exerciser in the 


order you need that information. The reference part describes each 
command in the IOX Command Language. 


4.1 INTRODUCTION 
This section serves the following functions: 


® Provides an overview of the steps involved in running an I/O 
exercise 


® Describes how the I/O Exerciser exercises different types of 
devices 


e Distinguishes between file-structured and non-file-structured 
volumes 


@ Categorizes the IOX commands by function 


4.1.1 Running an I/O Exercise 
Before you run an I/O exercise, you need to consider the following: 


e Kinds of devices to exercise (magnetic tapes, cassettes, 
disks, terminals, and DECtapes) 


@ Kind of exercises to run for each device (IOX has three kinds 
of exercises) 


@ Exercise parameters to set for each exercise (such as_ whether 
or not to test random blocks on disks, how many records to 
test on magnetic tapes, and how long to run the exercise) 


The steps involved in running an I/O exercise include your making 
decisions about these three aspects of testing. Using the IOX Command 
Language, you implement these decisions and run an exercise. 
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To run an I/O exercise, you must take the following basic steps: 
l. Invoke IOX. 


2. Determine which devices you want to test and include them in 
your "test configuration." 


3. Determine the kind of exercise to run on each unit in your 
test configuration. 


4. Set exercise parameters to affect how IOX tests the units you 
want to exercise. 


5. Begin the exercise and possibly interrupt the exercise to 
change steps 2, 3, and 4. 


6. Monitor the activity and error reports that IOX generates 
during an exercise. 


7. |Exit IOX or repeat this process beginning at step 2, 3, 4, or 
5, aS appropriate. 


4.1.2 How IOX Exercises Different Types of Devices 

IOX performs exercising on _ disks, magnetic tapes, cassettes, 
terminals, and DECtapes. You can use I0OX to perform an exercise 
operation on any mounted volume disk, magnetic tape unit, or terminal 
in your hardware configuration that has not been allocated to another 
user. By default, IOX can exercise 28 units simultaneously. You’ can 
edit the task build command file (see Section 4.11) to enable IOX to 
test as many as 250 units simultaneously. 

In general, I/O exercises consist of four steps: 


1. Writing bytes of data (made up of a specific data pattern) to 
a mounted volume 


2. Reading the data just written 
3. Checking that the data read matches the data written 
4. Reporting mismatches of data 


IOX repeats this process until the exercise has completed. 


4.1.2.1 How IOX Exercises Disks - IOX writes a buffer of data to a 
disk and then reads that data from the disk. You can also set 
exercise parameters that determine the following: 


@e The data pattern to be written 
@ The range of blocks to be tested 


@ Whether to test blocks sequentially or randomly 


4.1.2.2 How IOX Exercises Magnetic Tapes and Cassettes - IOX uses the 
same algorithm to exercise magnetic tapes and cassettes. I0OX rewinds 
the tape, writes one record, space reverses one record, and then reads 
the record that was just written. This procedure is repeated until 
the number of records that you specified for testing are read. At the 


4-2 
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end of the exercise, IOX writes two tape marks and rewinds the tape. 
If you are testing more than one unit, IOX continues testing on those 
units while the tape is rewinding. You can also set exercise 
parameters that determine the following: 


e The data pattern to be written 
e The size of the data buffer 


e The number of records to be exercised 


4.1.2.3 How IOX Exercises Terminals - IOX exercises terminals by 
continuously writing out a portion of the ASCII character set to a 
terminal that is not logged-in. If LOOPBACK NO (the default) is 
specified, this is all that happens. If LOOPBACK is specified, IOX 
will read the characters back after writing them, compare the two sets 
of characters, and report on the comparison between the two sets. 
(LOOPBACK mode requires that a loopback connector be connected in 
place of the terminal to direct the characters written back to IOX. 
IOX depends on the presence of a typeahead buffer to store the 
characters between writing and reading them. See Section 4.4 for 
further information on the LOOPBACK parameter.) 


4.1.2.4 How IOX Exercises DECtapes - IOX exercises DECtapes by 
writing forward/reading forward, then writing reverse/reading reverse 
until the end of the tape is reached. IOX exercises DECtapes using a 
data buffer of two blocks (1024(decimal) bytes). You can set a test 
parameter only to determine the data pattern that IOX writes to the 
DECtape. 


4.1.2.5 Non-File-Structured and File-Structured Volumes - IOX exer- 
cises devices on two kinds of volumes: non-file-structured (NFS) and 
file-structured (Files-ll). The meanings of these terms may differ 
slightly from other manuals within the RSX-11M/M-PLUS set. In the 
context of the I/O Exerciser, they are defined as follows: all tapes 
and terminals are NFS volumes. (Throughout this chapter, the term 
"NFS" describes devices and the testing of devices that contain 
non-file-structured volumes.) Disks can be either NFS or Files-1l 
volumes. Files-ll volumes are only those disks that have’ been 
initialized with the MCR INITIALIZE command and therefore have a home 
block and a Files-1ll structure. 


4.1.3 The Four Categories of IOX Commands 


The IOX Command Language has four categories of commands: 


1. Function Commands - Select devices for testing, deselect 
devices from testing, and initiate tasks to run in parallel 
with IOXx. 


2. Control Commands - Start and stop IOX processing, switch IOX 
modes of operation, and exit from IOX to the operating system 
monitor. 


3. Display Commands - Display current default parameters, get 
help text for IOX commands, and display status and activity 
reports during an I/O exercise. 
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4. Parameter Commands - Set default parameters that affect how 
IOX tests the devices you select for testing. 
Table 4-1 lists the IOX commands under their appropriate categories. 


Table 4-1 
Four Categories of IOX Commands 


Function 


DESELECT 
EXECUTE 
FILES11 
SELECT 
VERIFY 


1. These commands have two forms: 


Control 


ABORT 
CTRL/C 
EXIT 
PROCEED 
RESTART 
START 


Display 


BADBLOCKs 1 
CONFIGURE l 
DENSITY 1 
HELP 
PARAMETERLIST 
PATTERN 1 
PRINTSUMMARY 
RANGE l 

SPY 


Parameter 


BADBLOCKS 1 
BUFFERSIZE 
COMPAREDATA 
CONFIGURE 1 
CONTROL C 
DENSITy 1 
ERRORLIMIT 
INTERLEAVE 
LOGFILE 
LOOPBACK 
PATTERN l 
RANDOM 
RANGE 1 
RECORDS 
REPORTERRORS 
RETRIES 
RUNTIME 
SUMMARYTIME 
TEMPORARYFILE 
VOLUMECHECK 
WAIT 
WRITECHECK 


one that displays the 


current default for the parameter and one that sets the 
current default for the parameter. 


4.2 INSTALLING AND INVOKING IOX 


IOX is task built as a nonprivileged, checkpointable task that runs at 
a priority of 50 in the GEN partition. 
the RUN command from either MCR or DCL or by installing and invoking 


IOX. 


4.2.1 Installing IOX 


Install IOX from a privileged terminal with 


command. 


For RSX~11M systems that do not support the 
the RSX-11M/M-PLUS and Micro/RSX Executive 
IOX with an increment large 
initial 
unit to be tested simultaneously. 
install I0X as follows: 


Assuming all 


simultaneously, 


“INS $LOX/INC=1800, 


enough to accommodate 
IoX defaults, allocate 600(decimal) words per 
For example, to test three 


the 


You can run IOX by entering 


MCR or DCL 


Extend Task Directive (see 
Reference Manual), 
all buffers. 
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For RSX-11M systems that support the Extend Task Directive, install 
IOX without an increment. 


4.2.2 Invoking IOX 


You can invoke IOX from any terminal. 


On RSX-11M single user systems, mount all disks that you want to 
exercise as file-structured disks. If you have a multiuser system, 
first allocate all units that you want to exercise. Then mount only 
those disks that you want to exercise as file-structured disks. 


On RSX-11M-PLUS systems, allocate and mount all units that you want to 
exercise. Mount non-file-structured volumes using the /FOREIGN switch 
for the MOUNT command. 


4.2.2.1 Invoking an Installed Version of IOX - If IOX is installed, 
invoke it with the following command: 


»TOX 
LOX? 


IOX responds by prompting you with the name of the task that you 
assigned to IOX when you installed it. If you did not specify a task 
name when you installed IOX, its task name is ...IOX. After receiving 
the prompt, you can enter IOX commands. 


4.2.2.2 Invoking IOX When It Is Not Installed - If IOX is not 
installed, invoke it by entering the RUN command from either MCR or 
DCL. In this case, IOX uses your terminal number to name the task and 
prompts you using this task name. For example, if from TT10: you 
type the following: 


“RUN $TOX 
When you receive the following prompt, you can enter IOX commands: 
TV1iO> 


For RSX-11M systems, if your system does not support the Extend Task 
Directive, then run the I/O Exerciser with an increment large enough 
to accommodate all buffers. Assuming all initial I0X defaults, 
allocate 600(decimal) words per device to be tested simultaneously. 
For example, to test four devices simultaneously, invoke I0X as 
follows: 


© RUN SIOX/INC=2400, 


When you invoke an uninstalled version of IOX on RSX=-11M systems that 
support the Extend Task Directive, you do not need to run the task 
with an increment. 


When you invoke an uninstalled version of I0OX on RSX-11M-PLUS systems, 
you do not need to run the task with an increment. | 
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4.3 USING INDIRECT COMMAND FILES WITH IOX 


You can use indirect command files as input to IOX. IOX accepts’ one 
level of indirect command files. You can use indirect command files 
to set up your test configuration, choose devices for testing, set 
exercise parameters, and start and exit the exercise. You cannot 
interrupt an I/O exercise to enter IOX commands from an _ indirect 
command file. The default file type is "CMD." 


For example, use an editor to create a file named TEST.CMD that 
contains the following IOX command sequence: 


CONFIGURE DB2: ; Adds DB2: to the test configuration 


FILES11 DB2: Chooses DB2: for an exercise that preserves 


the contents and structure of the disk 


se Ne 


RUNTIME 10 ; Sets an exercise parameter that runs 
; for 10 minutes 


START >; Starts the exercise 


EXIT Exits from IOX to the operating system 


monitor when the exercise completes 


=e se 


After you invoke IOX, type the following: 
LOX RTEST 


IOX exercises DB2: (preserving its contents and structure) for 10 
minutes and then exits to the operating system monitor. 


4.4 SETTING UP A TEST CONFIGURATION 


Before you can exercise a unit, you must first include it in your test 


configuration. When you include a unit in your test configuration, 
IOX adds the unit to its list of units available for exercising and 
creates an empty data structure for the unit. IOX includes in the 


default test configuration one of each device type supported by 
DIGITAL as unit "O". 


To add units to the test configuration, you use the CONFIGURE command. 
The syntax for this command is as follows: 


CONFIGURE [ddnn:[=type]] .... 


where: 
ad The device mnemonic 
nn The device number 


type The device type, either DISK, TERM, or TAPE 


You can add any unit to the test configuration and assign a logical 
device name to it by using the MCR ASN (ASSIGN) command. 
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The CONFIGURE command with no arguments displays the current test 
configuration. For example: . 


TOxX> CONFIGURE 


Ttisks3 

“ko 0G TFO PRO PFO DMO TRO NRO TSG Title 
mxo YO EMO SYO 

Tares 

CTO [TGQ MFO MMO NSO MTG MUG 
Terminals? 

TO 


To add DKl: and MM1l: to your configuration, type tne following: 
TOX> CONFIGURE DEL?  MMmit 


This command line adds DKl: to the configuration as a disk unit 
(because DKO: is already configured as a disk) and MMl: to the 
configuration as a tape unit (because MMO: is already configured as a 
magnetic tape). Section 4.12 describes the CONFIGURE command in 
detail. 


To add TT12: to your configuration, type: 
TOXxXS CONFIGURE TT12% 


This command line adds TT12: to the configuration as a terminal unit 
(because fMTTO: is already configured as a terminal.) If you want to 
exercise your terminal using LOOPBACK mode, the following terminal 
characteristics must be set BEFORE installing the LOOPBACK connector: 
SLAVE, PASSTHRU, NOECHO, LOWERCASE, and NOWRAP. The line must also be 
logged out. 


For Loopback mode, IOX relies on the typeahead buffer to store the 
characters it writes before reading them. For this reason, IOX limits 
the number of characters it writes to the size of the typeahead 
buffer, and does not operate if typeahead is disabled. 


4.5 SELECTING DEVICES FOR EXERCISING 


After configuring all the units you want to exercise, you select units 
for exercising. When you select a unit, IOX fills in the data 
structure created when you configured the unit. This data structure 
contains all the information IOX needs to exercise the specified unit. 
You select units for exercising with the FILES11, SELECT, and VERIFY 
commands. These commands require device and unit specifications 
within their command lines. 


4.5.1 The FILES11 Command 


The FILES11 command selects a disk unit with a mounted Files-1ll volume 
for an I/O exercise. Exercising with FILES11 does not affect the 
contents of the disk being tested. 
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4.5.2 The SELECT Command 


The SELECT command selects a unit with an NFS volume for an I/O 
exercise. Invoking the exercising function by using the SELECT 
command will destroy the contents of the volume being exercised. The 
SELECT command is also used to select a terminal for exercising. 


4.5.3 The VERIFY Command 


The VERIFY command selects a disk unit with a mounted NFS volume _ for 
an I/O exercise. VERIFY does not write on the volume being exercised. 
Exercising with VERIFY does not affect the contents of the volume 
being exercised because VERIFY only reads from the volume. 


4.6 EXERCISE PARAMETERS 


You set parameters that determine how IOX exercises units. These 
exercise parameters determine aspects of testing such as how long an 
exercise is to run, how many records are tested on magnetic tapes, 
what range of blocks are tested on disks, and whether output is 
directed to your terminal or to a log file. There are two kinds of 
exercise parameters: general and device dependent. 


4.6.1 General Exercise Parameters 


The following commands set general exercise parameters and, therefore, 
affect all IOX testing: 


CONFIGURE 
CONTROL C 
LOGFILE 
PATTERN 
REPORTERRORS 
RUNTIME 
SUMMARYTIME 


4.6.2 Device-Dependent Exercise Parameters 


You use the commands listed in this section to set default parameters 
for the units that you select for exercising. You can include these 
commands within the FILES11, SELECT, and VERIFY command lines to 
override the default parameter for the specified unit. 


4.6.2.1 Parameter Commands for Files-ll Disks with FILESI11 - The 
following commands affect the exercising of disks that you select with 
the FILES11 command: 


COMPAREDATA 
ERRORLIMIT 
INTERLEAVE 
RANDOM 
TEMPORARYFILE 
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You can use these commands to set the default parameters before you 
use the FILES11 command to select a unit. You can also use these 
commands within the FILES11 command line to override the default 
parameters for the unit being selected. 


4.6.2.2 Parameter Commands for NFS Volumes or Terminals with SELECT - 
The following commands affect the exercising of NFS volumes or 
terminals that you select with the SELECT command: 


BADBLOCKS RANDOM 
BUFFERSIZE RANGE 
COMPAREDATA RECORDS 
DENSITY RETRIES 
ERRORLIMIT VOLUMECHECK 
INTERLEAVE WRITECHECK 
LOOPBACK 


You use these commands in conjunction with the SELECT command to. set 
default parameters for exercising a terminal or a unit with an NFS 
volume. You can use all but BADBLOCKS within the SELECT command line 
to override the current default settings for the device being 
selected. 


Table 4-2 lists the parameters for exercising different types of 
devices. 


Table 4-2 
Parameter Commands by Device Type for SELECT 


NFS Disks Cassettes DECtapes Magnetic Terminals 
Tapes 


BADBLOCKS 1 BUFFERSIZE COMPAREDATA BUFFERSIZE BUFFERSIZE 
BUFFERSIZE COMPAREDATA ERRORLIMIT ERRORLIMIT COMPAREDATA 
COMPAREDATA ERRORLIMIT DENSITY ERRORLIMIT 
ERRORLIMIT RECORDS RECORDS LOOPBACK 
INTERLEAVE RETRIES 

RANDOM 

RANGE 

RETRIES 

VOLUMECHECK 

WRITECHECK 


1. Cannot be used within SELECT command line. 


4.6.2.3 Parameter Commands for NFS Volumes with VERIFY - The 
following commands affect the exercising of NFS disks that you select 
with the VERIFY command: 


BADBLOCKS 
BUFFERSIZE 
ERRORLIMIT 
INTERLEAVE 
RANDOM 
RANGE 
RETRIES 
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You use these commands with the VERIFY command to set default 
parameters for testing a unit with an NFS disk. You can use all but 
BADBLOCKS within the VERIFY command line. 


4.7 SETTING PARAMETERS FOR EXERCISING FILES-11 VOLUMES 


This section shows you how to use IOX to exercise an RLO2 with a 
Files-ll structure. Example 4-1 uses the following IOX commands: 


PARAMETERLIST 


Displays current default parameters, IOX buffer space statistics, 
and device-dependent parameters for devices you have selected for 
testing. 

RUNTIME 


Sets the length of time (in minutes) that IOX exercises the 
unit(s) you have selected for testing. 


FILES11 


Selects a disk with a mounted Files-1ll volume for an I/O exercise 
that preserves the contents and structure of the disk. 


TEMPORARYFILE 


Sets the size of the temporary file that IOX uses for testing 
Files-1l disks with the FILES11 command. 


START 


Starts exercising units that you have selected for testing. 


Example 4-1 Exercising an RLO2 with the FILES11 Command 


PALL TL Os 1) 
MOU Thoe LOUTE @ 
= LOM 3) 


LOXSPARAME TERL TST 


RUFFERS TEs 1O34, COMPARERATA= YES 

SRROQRLIMIT= 10. CONTROL C= YES 

iHTERLEAVES 4, LOGFILE = AO 

PATTERN ©. LOOPBACK = NO 

RECGHNSs L1o04, RANTIOM= YFS 

RUNTIME: 3. 7) REPORTERRORS= YES 4) 
SUMMARY TIME 2. RETRIES= YFS 

TEMPORARYFILE= SOO, 8] YOLUMECHECK= YES 


WATT= YES 
WRITECHFECK= NO 
Buffer Grace ussdeas SFO, 21 S54. 1 9e4ae tl. 
TOxXx>RUNTIMNE 3 e 
LOX: FTES THh.Gt JEMPs Soo 
(OKOPARARETER ® 


(continued on next page) 
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Example 4-1 (Cont.) Exercising an RLO2 with the FILES11 Command 


evice Mode EBuffersizve Filesizve/Records/KRande Peremneters 


ee nese com tear cose, sone ones cose cece cess ome cow wees come nee tak eee cone sone nese cous ones ener euan eter seat sem seem com Game quer cues ones cee sem coms sem, 


owe care cnet cou sens cece come cece ares ones 


TL O 3 Fil <i gee ROO, 10) COM RET RAN ERR=16, 
BUFFERSTZE= 1024, COMPAREDATA= YES 
ERRORLIMNE T= 19, CONTROL C= YES 
INTERLEAVE= 4. LOGFILE = NO 
PATTERMN= 0, LOOPBACK = NO 
RECORUS= 1024, RANTOM= YES 
RUNTIME 3, 7) REPORTERRORS= YES 
SUMMARYTIME= 1. RETRTES=. TES 
TEMPORARYFILE= 500. © VOLUMECHECK= YFS 
WATT= YES 


WRITECHECK= NO 


Raffer rare asacas NSOO.,TTA9R.T1TaGR. id. 


LOXSSTART 


@ 


The command sequence in Example 4-1 does the following: 


oo 090 


6) 


Allocates drive DLO:. 
Mounts the disk with label "LOUIE" in DLO:. 


Invokes an installed version of IOX with default task name, 
oe @¢ -~1OXx. 


Displays the initial default parameters with PARAMETERLIST. 
Changes the default RUNTIME to 3 minutes. 


Selects DLO: for FILES11 testing with a temporary file size 
of 800 blocks. 


Note the difference between the defaults displayed by the 
PARAMETERLIST command before and after you changed RUNTIME and 


selected 


3) 
9] 


DLO:. 
Only the RUNTIME default has changed. 
The default for TEMPORARYFILE has not changed. 


After you selected DLO: for testing, PARAMETERLIST contains 
an extra line at the beginning that displays all 
device-dependent parameters: for the selected device. Each 
selected device has its own display line. There are five 
fields of parameters. 


Field four shows that the temporary file size used for 
FILES11 testing for DLO: is 800(decimal) blocks instead of 
the 500(decimal) block initial default. During FILES11 
testing, this field refers only to temporary file size. 


The START command begins FILES11 testing on DLO: for a 
RUNTIME of 3 minutes and uses a temporary file size of 
800(decimal) blocks. 
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4.8 SETTING PARAMETERS FOR EXERCISING NFS VOLUMES 
This section shows examples for the command sequences that test a 


magnetic tape volume using the SELECT command and an NFS disk using 
the VERIFY command. Both examples are explained in detail. 


4.8.1 Exercising a Magnetic Tape with the SELECT Command 

The command sequence in Example 4-2 tests a magnetic tape by using a 
buffer of 8K bytes (which contains the data pattern 052652) to 
transfer data. 

Example 4-2 illustrates the following commands: 


PARAMETERLIST 


Displays current default parameters, IOX buffer space statistics, 
and device-dependent parameters for devices you have selected for 
testing. 
PATTERN 
Sets the pattern that IOX writes and reads during an exercise. 
BUFFERSIZE 
Sets the amount of data that IOX transfers for every read or 
write request when testing NFS disks, magnetic tapes, and 
cassettes. 
DENSITY 
Sets the density and characteristic word of the specified 
magnetic tape or displays the current density and characteristic 
word for the specified magnetic tape unit. 


SELECT 


Selects a unit with a mounted NFS-~ scratch volume for an I/O 
exercise that destroys the contents of the volume 


RETRIES 
Determines (for magnetic tapes and NFS disks) whether an I/O 
driver repeats an I/O operation after the driver receives errors 
during the operation. 


ERRORLIMIT 


Sets the maximum number of errors that IOX tolerates between 
interval reports before terminating testing on a device. 


RECORDS 


Specifies the number of records to be exercised on magnetic tapes 
and cassettes. 


START 


Starts exercising units that you have selected for testing. 
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EXIT 


Terminates IOX processing and'exits from IOX. 


Example 4-2 Exercising a Magnetic Tape with the SELECT Command 


ALL MMOS 
MOU MMOS 1) 
= TOX 
TOX™FARAMETERL LST 


RUFFERSTZE= 1024, 8) COMFARETATA= YES 
KRAORL IME T= 30, CONTROL JOC YES 
INTERLEAVE= 4. LOGF TLE NO 
PATTERN: 0, © LOQFRACK= NO 2) 
RECOROG= 1024, RANTIOM= YES 
RUNTIME = of, REFORTERRORS= YES 
SUMMARYTIME= 1. RETRIFS= YES 
TEMPORARYFILE= S00, VOLUMECHECKR= YFS 
WATT= YES 
WRITECHECKR= NO 


Buffer seanca wmsaces SPO, T1384, 21904. 91. 


LTOXSPATTERM 42 © 
LOXSRUFFER 8492 4) 
TOXS HENS MAGS 

Nenettyus 14090 BPT Rnaracteriebic Word= 6046004 Cnoetal) 5) 
TOXSSFLECT MMOGS REFTRTES=NO NENSTTY=R00 FRROR=16060 RFC= 70000 @ 
TOXSFARAM 


"7 


Vevieoe Mode Buffersize Filesizve/Recardse/Ranse Feaerameters 


snes seme toe pee eens come ate roe ote es sete wee eee set ence come -20s com ease wee acer Seen seen team cone etsy nea cae same snes mews Stee rte com meet atte anat eae stat rem come one foree went eee seme comm ome come sees meet sees 


MMOS NFS ee ee ea @ 2O000. 12) COM FRR=1¢0, © 


BRUFFERSIAZR# 8192, 8] ROMPARETATA= YES 
ERRQELIMIT= 29, COHTROL C= YES 
THUERLEAVE =: 4, LOGE TLE = NO 
PATTERN: 12, © LOUPRACK= NO 
RECORD S= 1024, RANTIOM= YES Q 
RUNTIME S. REFORTERRORG= YES 
SUMMARY TIME= 1. RETRTRS= YES 
TEMPORARYFILE= Soo. VOLUMPCHFOR= YES 
WATT= YES 
WRITECHECK= NO 


Buffer geace sGgades JS505R.IB8188. fen 92 3%. 


TOXSDENSITY MRO? 


HOO RRL Cnerseterisatic Woard= 6900900 Coctal) 


WUER owe MMOS band pioecks JIS Cdecimeld 140 (actal) 


LOX -~ Summarys of exerciser aethivity at 29-.UL-85 1469590740 
TAF -- Rum? domain. Flaeseds io ominm. Remainimst? 4 mim. 
MMO? -~ 330. R/W reeuegts totaling 230, records with fo errors 
AST’s executed? S44. 
Tchle@-Tooe tlerationme? 344, 


(continued on next page) 
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Example 4-2 (Cont.) Exercising a Magnetic Tape with the SELECT Command 


TOX -- MMO? bed block, 4846 (decimal) 746 Coctal) 
TOX ~-- MMO? bach Oloeks SSL (decimal) 1047 Coctal) 


T0Q4 -- Summary of exerciser sebivity at 2O-JUL-85 146¢54150 
TIME -~ Reurmd Lo ominme Elaresartt To min. Remaining? G mite 
MMOS -- O17. R/W reauests totaling 217. records with ? errors 
AST’s execubed? 3A, 
Idle-looe iterations? SF. 


Aer! Mw ob A TE TO TAL § ? 
TIMF -~ Rum? S mire Elaerced? S min. Remainios? O mine 
MAD -- Joel. B/W reeuests totaling lyiPi. records with | errors 


AST’s execubed?! 1,484, 
Idle-loor iterations? 194790. 


TOXSE KITT 


The command sequence in Example 4-2 does the following: 


@ Allocates drive MMO:, mounts the magnetic tape, and invokes 
an installed version of IOX. 


On RSX1IM-PLUS systems, you mount the tape with the /FOREIGN 
switch. | a ehh 


Displays the initial defaults. 
Selects pattern number 12 to be written to the tape. 


Changes the default BUFFERSIZE from 1024 (decimal ) to 
8192(decimal) (8K). 


Displays the default density and characteristic word on the 
magnetic tape mounted in drive MMO:. 


o 6© 68 8 


Selects MMO: for NFS testing with SELECT, overriding the 
defaults for RETRIES, ERRORLIMIT and RECORDS, and sets the 
tape density at 800(decimal). 

Checks the parameters with PARAMETERLIST and DENSITY. 
Changes the BUFFERSIZE default. 

Changes the PATTERN default. 

Displays the device display line for MMO:. 

Shows the current BUFFERSIZE of MMO:. 


Shows that the number or records to be tested is 20000. 


Starts NFS testing with SELECT on MMO:. 


©®eeedgo0od 


The remainder of Example 4-2 shows interval reports, error reports, 
and accumulated totals generated at your terminal during this 
exercise. These reports are discussed fully in Section 4.10. When 
the exercise has finished, you exit to the operating system monitor 
unless you want to do more testing. 
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4.8.2 Exercising with the VERIFY Command 


The command sequence in Example 4-3 performs oscillating seeks between 
blocks 1 and 1000 to align disk heads. It reads only 4 bytes per data 
transfer, which is the minimum. No error or summary reporting is 
required. The exercise runs until you abort it. 


Example 4-3 illustrates the following commands: 
PARAMETERLIST 


Displays current default parameters, IOX buffer space statistics, 
and device-dependent parameters for devices you have selected for 
testing. 


VERIFY 
Selects a mounted disk for an NFS exercise that reads buffers of 
data without writing on the disk, performing data comparisons, or 
destroying the contents of the disk. 

RANGE 


Sets the minimum and maximum block numbers for NFS testing on the 
specified disk. 


BUFFERSIZE 
Sets the amount of data that IOX transfers for every read or 
write request when testing NFS disks, magnetic tapes, and 
cassettes. 


RANDOM 


Directs IOX to select either random or sequential blocks for disk 
testing. 


INTERLEAVE 


Sets the number of blocks to be skipped before IOX writes the 
next buffer of data for disk testing (applies only to sequential 
testing which you determine with the RANDOM command). 


ERRORLIMIT 


Sets the maximum number of errors that IOX tolerates between 
interval reports before terminating testing on a device. 


REPORTERRORS 
Enables or disables error reports. 
SUMMARYT IME 


Determines how often (in minutes) IOX will output interval 
reports. 


RUNTIME 


Sets the length of time (in minutes) that IOX exercises’ the 
unit(s) you have selected for testing. 
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LOGFILE 


Determines whether IOX directs activity and error reports to your 
terminal or to a log file. 


START 
Starts exercising units that you have selected for testing. 
CTRL/C 


With CONTROL _C enabled, allows you to enter IOX commands while an 
exercise is in progress. 


ABORT 


Terminates execution of an I/O exercise. 


Example 4-3 Exercising an NFS RKO7 with the VERIFY Command 


ALL TIMOt 

“MOU DMO 1) 

» LOX 

LOX® FAR 

BUFFERSIZE= 1024, COMPAREDATA YES 
ERRORLIMIT= 10. CONTROL.C= YES 
INTERLEAVE= 4, LOGEILE= NO 
PATTERN= 0. LOOPRACK= NO 
RECORDS= 1024, RANDOM= YES 
RUNTIME= 5, REFORTERRORS= YES ?@ 
SUMMARYTIME= 1. RETRIES= YES 
TEMPORARYFILE= 500, VOLUMECHECK= YES 


WATT= YES 
WRITECHECK= NO 


Buffer srare usade= 3SI9O,T1T 924, P18 24.31. 


LOX=VERIFY [IMO RANGF=131000 BUF=4 RANTI=N INTER=999 ERR=50000 © 
LOXSREPORTERRORS NO 

TOX=SUMMARY © ry 

LOX*RUNTIME 6 

1OX2L.08 Y 

LUXS PAR 


Vevice Mode Kuffersize Filesive/Records/Range Farameters 


IMO 3 VFY 4. ie oe Le OOO. RET INT=999, ERR=30000, 
BUFFERSIZE= 1024, COMPAREUATA= YES 

ERRORLIMIT= 10, CONTROL C= YES 

INTERLEAVE= 4. LOGFILES YES 

PATTERN= QO, LOOFBACK= NQ 

RECORDS= 1024. RANDOM] YES 

RUNTIME= O-¢ REPORTERRORS= NO 

SUMMARYTIME= 0. VOLUMEFCHECK= YES 

TEMPORARYFTLFE= S00, WAIT= YES 


WRITECHECK= NO 
Buffer srace usade= S290.T1T9LTP.t191eesd. 


LOX2ST 
LOX=7C » © 


TOX>ABORT 
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The command sequence in Example 4-3 does the following: 


@ Allocates drive DMO:, mounts the RKO7 for NFS testing, and 
invokes IOX. 


On RSXLIM-PLUS systems, mount disks with the /FOREIGN 
switch. ae oe 2 


@ Displays the initial default parameter. 


© Selects DMO: for read-only NFS testing with VERIFY, 
overriding the following defaults: 


a. RANGE -- blocks 1 through 1000 
b. BUFFERSIZE -- minimum, four bytes 


c. RANDOM block testing turned off and INTERLEAVE set at 
999 so that IOX tests only blocks 1 and 1000 


d. ERRORLIMIT set impossibly high (50000.) so that IOX will 
not deselect DMO: no matter how many errors are 
encountered during the exercise 


(4 ] Turns off REPORTERRORS so that no error’ reports are 
generated. Turns SUMMARYTIME off so that no interval 
reports will be generated. Sets RUNTIME to zero so that IOX 
runs the exercise until you abort it. Sets LOGFILE YES to 
direct all output to the log file, IOX.LOG, instead of to 
the terminal. 


15] Shows that the RUNTIME, SUMMARYTIME, and LOGFILE defaults 
have been reset and that DMO: is being tested with VERIFY, 
using a buffersize of 4., over a range of 1000. blocks, 
with RETRIES enabled, INTERLEAVE set at 999, and ERRORLIMIT 
set at 50000. 


@ Shows how to start the exercise using the START command and 
enter Interactive Mode with CTRL/C so you can enter the 
ABORT command to abort the exercise. 


Example 4-4 shows the contents of the log file for Example 4-3. 
Example 4-4 Log File Output for Example 4-3 


LOX -- 2O-JUL-8E PASSA i 2s REKHHAREK EXERCISER STARTETD EEEKKKKE 


levies Meaache GufPersise Filesisze/Rerorgde/Rande Parameters 


TMO ¢ wey 4, ta e+ Le Ooo. RET INT=999, FRR=50000, 


RUFFERSIZE= 1004, COMPARETATA= YFS 
ERRORLIMET= 16. CONTROL C= YES 
INTERLE AVES 4, LOGFILE= YES 
PATTERNS ©. LOQPRACK= NO 
RECORDS: 1OO4, RANTIOM= YES 
RUNTIME }, REPORTERRORS= NO 
SUMMARYTIMNE= G, BRETRIES= YES 
TEMPORARYPTLE= Soo, VOLUMECHECK = YES 


WATT= YFS 
WRETECHECK = NO 


(continued on next page) 
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Example 4-4 (Cont.) Log File Output for Example 4-3 
Buffer srare usade= 32°O,f1 812. f1B1e.t1. 


[OX -- Summary of exerciser sebtivity et 2O-JUL-RS 1at2 
TIME ~~ Rais 3 omitte Elareserd? 3 min. Remainims? 45535 mins 
MOP -- SrO75, RW reanests toteling 279075. hincks with mo errors 
A$Yoo execubed? 3»G81, 


tdde-loor iterations? 2-982, 


Boo GL ke cee Be PT hed eee 


TYME -- Runt & min. Fhlergecd? 3 mime Remeinisd? S533 tmtris 
UMOTA -- 22076, R/U renuests totalins 49074. blocks with mo errors 
AST“ eyeciberc? F082, 
Iddte-Toor alterations: P+eGGo, 

TK -- 36-0 -RS Biter isd RARER ES HY EX FRO ISER ARNDRTED RREKERKE 


The log file output terminates when you abort the Exerciser. The log 
file begins with the time and date that the exercise began and the 
current default parameters as displayed by the PARAMETERLIST command. 


4.9 IOX OPERATING MODES 


IOX operates in three modes: Command, Execution, and Interactive. 
This section discusses the functions of these modes, how you enter and 
exit each mode, and what IOX commands are valid in each mode. 


4.9.1 Command Mode 


IOX is in Command Mode after you have invoked it and have received the 
first IOX prompt. (Section 4.2 discusses IOX prompts.) In Command 
Mode, no devices are being exercised, and tasks initiated by the 
EXECUTE command are queued but not active (see Section 4.12 fora 
complete description of the EXECUTE command.) You’ usually set 
parameters, select devices for testing, and initiate tasks to be 
executed in Command Mode. 


When you press the RETURN key, you receive an IOX prompt. When you 
press CTRL/C, you exit to MCR for one command line. 


4.9.2 Execution Mode 


When you begin an I/O exercise by entering the START command, I0OX 
exits Command Mode and enters Execution Mode. Once you have entered 
Execution Mode, exercises begin on selected devices, tasks initiated 
with the EXECUTE command begin executing, the IOX clock is turned on, 
and activity and error reporting begin. 


You set the CONTROL C parameter in Command Mode to allow or disallow 
you to enter IOX commands while an exercise is in progress. CONTROL C 
YES is the initial default setting. 
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If you have set CONTROL C NO, then CTRL/C in Execution Mode gives 
control to MCR and you receive the MCR prompt (>) every time you press 
the RETURN key and "MCR>" every time you press cCTRL/C until the 
exercise has terminated. With CTRL/C disabled, you cannot interrupt 
the exercise, however, you can terminate it with the MCR’ ABORT 
command. , 


If you have set CONTROL C YES, IOX does not accept any input from your 
terminal except CTRL/C. If you try to enter anything but CTRL/C, you 
receive an error message for each key you press: 


TQX -- Onde “C Allowed 


When you press CTRL/C, you receive the IOX prompt instead of the MCR 
prompt and IOX exits Execution Mode and enters Interactive Mode. 


4.9.3 Interactive Mode 


You have access to Interactive Mode only if CONTROL C is’ enabled. 
When you press CTRL/C in Execution Mode, IOX exits Execution Mode and 
enters Interactive Mode. In Interactive Mode, the RETURN key and 
CTRL/C have the same functions that they have in Command Mode. 


In Interactive Mode, the exercise and tasks initiated by the EXECUTE 
command are running. Activity reports and error’reports directed to 
your terminal are suspended if you have set LOGFILE=NO. If you have 
set LOGFILE=YES, activity and error reports continue as in Execution 
Mode. 


All IOX commands except the following are valid in Interactive Mode: 


BUFFERSIZE 
PATTERN 
RUNTIME 
START 
RESTART 


If you enter these commands, IOX prints the error message: 


tO¥ -- Command velic onles tn command made 


You can use the BUFFERSIZE command within the SELECT and VERIFY 
command lines to override the current defaults for the device being 
selected, but the BUFFERSIZE command cannot be used by itself to reset 
the default. 


Although you cannot use the PATTERN command to choose a different 
pattern to be written to the volumes being tested, you can use PATTERN 
with no argument to display all the patterns. 


The following commands are valid only in Interactive Mode: 


ABORT 
PRINTSUMMARY 
PROCEED 

SPY 


Although you can use PRINTSUMMARY and SPY in Command Mode _ without 
generating an error message, these commands display meaningful 
information only when you use them in Interactive Mode. 


When you use the ABORT command, IOX exits Interactive Mode and enters 
Command Mode. The ABORT command with no qualifiers terminates all 
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exercising and all tasks initiated by the EXECUTE command. This form 
of ABORT is valid only in Interactive Mode because in Command Mode 
there can be no exercise or active tasks to abort. 


The PROCEED command exits Interactive Mode and enters Execution Mode 
unless no activity remains when you issue PROCEED, in which case IOX 
aborts the exercise. 


4.10 IOX OUTPUT 


IOX generates two types of output: activity reports and error 
reports. Activity reports summarize IOX processing information, such 
as how long an exercise will run and how many ASTs have been executed. 
There are two kinds of error reports: data compare error reports, 
that show where IOX finds errors on the volume being tested, and 1/0 
error reports, that indicate failed QIOs from a driver. You use the 
LOGFILE command (see detail in Section 4.12) to direct activity and 
error reports to your terminal or to a log file. 


4.10.1 Activity Reports 
There are three types of activity reports: 


1. Accumulated Totals - An activity report at the end of an I0OX 
exercise that reports the activity for the entire exercise 


2. Interval Reports - An activity report that summarizes I0OX 
activity in the time intervals set by the SUMMARYTIME command 


3. Summary Reports - A report of activity between the last 
Interval Report and the time you enter the PRINTSUMMARY 
command to request a summary report. 


Section 4.12 discusses the SUMMARYTIME and PRINTSUMMARY commands’ in 
detail. 


4.10.1.1 The Format of Activity Reports - The formats of activity 


reports are indentical except for the first line. Interval and 
summary reports begin with the time and date of the report. For 
example: 

TOR =< Sutmersv of B@xerociger agebtivity at PO-IU-8h 113163276 


The accumulated totals report does not give the time or date of the 
report and begins: 


ROR We AN TE. TA TAL §$ 3 


4.10.1.2 The Content of Activity Reports - The content of all 
activity reports is identical. The following is an interval report of 
an exercise that tests SYO:. 


INX -- Summary of exerciser aetivity at Si-TFEO-85 11itisbiegy 

TIME -~- Rum? domain. Elarsed? 2 mits Remaining: 3 min. 

SYO? -- 17874. R/W reauests totaling 19874. blocks with mo errors 
ASTs executed? 17875. 

Idle-loor iterattonms; t808, 
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The activity report contains the following information: 
e Timing information 
- Time between reports as set in the SUMMARYTIME command 


- Time that the exercise has been in progress to the nearest 
minute 


- Time remaining to the nearest minute before the exercise 
will finish 


e Unit information for each unit being tested 


Number of I/O requests to the unit 


Number of blocks exercised for disks and tapes 


Number of bytes exercised for terminals 


Number of error encounters on the unit 


@e Number of ASTs executed 
@ Number of iterations through the idle loop 


You use the following commands to control the output of activity 
reports: 


LOGFILE 
PRINTSUMMARY 
SPY 
SUMMARYTIME 


Section 4.12 discusses each of these commands in detail. 


4.10.2 Error Reports 


You use the REPORTERRORS command to enable or disable error reports. 
Section 4.12 discusses the REPORTERRORS command in detail. There are 
two kinds of error reports: data compare error reports and I/O error 
reports. 


4.10.2.1 Data Compare Error Reports - A data compare error means that 
the driver returned a success I/0 code to IOX but that the data 
written to the volume and the data read from the volume did not match. 
The following is an error report generated by a data compare error: 


IOX -~ DR1l: data compare error at block 33,937 (decimal) 102221 (octal) 
Good Data: 005767 Bad Data: 155555 
Word Position: 0 (decimal) 0 (octal) & 
Buffer contained 255. additional errors 


0 Identifies the device on which IOX encountered an error. It 
reports the starting block (in both decimal and octal) in 
which the error was found. 


@ Shows the "good data" that IOX wrote to the volume and the 
“bad data" that IOX read from the volume. Only the first 
error encountered in the test buffer is reported. 
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© Shows the position of the first word in the test buffer that 
generated a mismatch during the current operation. Only the 
first error encountered in the test buffer is reported. 


4) Shows how many other errors were found in the test buffer. 


4.10.2.2 1/0 Error Reports - There are 12 I/O errors. If a QIo 
fails, the driver returns an I/O failure code to IOX. IOX generates a 
specific I/O error report as a result of the following I/O errors: 


I/O Code Description 
IE.ABO Operation aborted 
IE.BBE Bad block 

IE.DAO Data overrun 

IE.DNR Device not ready 
IE.EOT End-of-tape detected 
IE.FHE Fatal hardware error 
IE.OFL Device off-line 
IE.PRI Privilege violation 
IE.VER Unrecoverable error 
IE.WCK Write check error 
LE.WLK Write-lock error 
N/A Unexpected error 


These error codes are shown in the RSX11M/M-PLUS I/O Drivers Reference 
Manual. Section 4.13 of this chapter presents the format and content 
of the 12 error messages that IOX generates because of these error 
codes. 


4.11 THE TASK-BUILD FILE 

You can change the initial defaults for IOX parameters as well as 
other defaults of the I0X.TSK by editing the IOX task-build file, 
IOXBLD.BLD. 


On RSX-11M systems, this file is located on your system disk in UFD 
[1,24] for mapped systems and [1,20] for unmapped systems. 


On RSX-11M-PLUS systems, this file is located on your system disk in 
UFD [1,24]. 


4.12 COMMAND DESCRIPTIONS 


This section provides complete descriptions of the commands in the I0X 
Command Language. Each command description includes the following: 


@e Kind of command by category: Function, Display, Parameter, 
and Control. 


@ All command formats. 
@e Qualifier descriptions. 
@ Operating mode restrictions. (Where no mode restrictions are 


placed on a command, it is valid in Command Mode and 
Interactive Mode.) 
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e Kinds of devices and testing to which the command applies. 

e Initial defaults, if applicable. 
The commands are presented alphabetically. 
Commands may be issued in all uppercase, all lowercase, or part upper 
and part lowercase. You can abbreviate commands using any combination 
of characters that appear unique to the IOX Command Language. 
All commands are represented by unabbreviated uppercase letters. All 
lowercase words in the presentations of command syntax indicate that 
you substitute alphanumeric characters for the word. 


All numerical qualifiers are decimal. 


Brackets [ ] indicate optional elements in the command line. 


ABORT 


ALBORT] [/ALL] 


[taskname] 
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The ABORT command is an IOX control command. You cannot use the ABORT 
command to abort a task that has attached your terminal, such as PIP. 


There are three forms of ABORT: 


ABORT 


ABORT/ALL 


ABORT taskname 


Terminates the execution of an I/O exercise and 
tasks initiated by the EXECUTE command. This form 
of ABORT is valid only in Interactive Mode 
(testing in progress) because in Command Mode (no 
testing in progress) there can be no running 
exercise or active tasks to abort. 


In Interactive Mode, this form of ABORT terminates 
the execution of all tasks initiated by the 
EXECUTE command and removes the tasks from the 
list of tasks to be executed. In Command Mode, 
this form of ABORT removes all tasks from the list 
of tasks to be executed. 


In Interactive Mode, this form of ABORT terminates 
the execution of a task initiated by the EXECUTE 
command and removes the task from the list of 
tasks to be executed. In Command Mode, this form 
of ABORT removes the task from the list of tasks 
to be executed. 
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BADBLOCKS 


BALDBLOCKS] ddnn: [blocknumbers ] 


You can use BADBLOCKS as a device-dependent parameter command or as a 
display command. Note that the BADBLOCKS command applies only to NFS 
disk testing. 


BADBLOCKS requires a device specification "dduu:". To use the 
BADBLOCKS command, the disk that you specify must already be selected 
for NFS operations. 


BADBLOCKS as a Parameter Command 

With the BADBLOCKS Parameter Command, you can omit the bad blocks’ on 
your disk from IOX testing. BADBLOCKS does not find bad blocks on 
your disk; it allows you to enter those blocks that the BAD utility 
has reported to be bad into an IOX bad blocks list for the disk. When 
you exercise the disk with SELECT or VERIFY, the blocks that you 
entered in the list will not be exercised. IOX omits only those 
blocks that you listed as block numbers in the BADBLOCKS command line; 
blocks marked as bad by the BAD utility but not entered into the bad 
blocks list with the BADBLOCKS command are treated as good blocks’ by 
IOXx. 


Once you have made entries in the bad blocks list for a disk, the 
block numbers that you entered remain on the list until you deselect 
the disk. 


There are two formats for entering bad blocks into the bad _ blocks 
list. One format is illustrated in the following two examples: 


BADBLOCKS DM1: 3 


This command line (which uses DMl: as an example) enters block 3 in 
the bad blocks list for DMl:. 


BADBLOCKS DM1: 3,4,5,11,12,13,99,151 


In this second example, the command line enters blocks 3, 4, 5, 11, 
12, 13, 99, and 151 into the bad blocks list for DMl:. 


The second format has the following form: 
beg:num 
where: 
beg Beginning block number. 
num Number of sequential blocks. 
For example: 
BADBLOCKS DM1l: 3:3,10:4,100:50 
This command line enters blocks 3 through 5, 10 through 13, and _ 100 


through 149 into the bad blocks list for DMl:. You can use this 
format for the length of a single command line. 
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BADBLOCKS (Cont.) 


You can use the two formats together on the same command line. For 
example: 


BADBLOCKS DM]: 3:3,10:4,99,100:50,151 


This command line enters blocks 3 through 5, 10 through 13, 99, 100 
through 149, and 151 into the bad blocks list for DMl1:. 


BADBLOCKS as a Display Command 


BADBLOCKS with no block numbers specified is a Display Command. For 
example: 


BADBLOCKS DM1: 

This command line displays the bad blocks list for DMl:. If you type: 
BADBLOCKS DM1: 3:5,10:4,99,100:50,151 

IOX would display: 


000003:005 
000010:004 
000099:051 
000151:001 


IOX displays the bad blocks list using a variation of the second 
format. It strings consecutive blocks together even if you did not 
enter them using the second format. For example, in the command line, 
you entered: 


99,100:50.... 


However, when IOX displays the bad blocks list, it does not separate 
these because blocks 99 and 100 are consecutive blocks. It does not 
display two lines: one for block 99 and one for blocks 100 through 
149. Instead, it displays (line three) the bad blocks list in one 
line as if you had entered 51 blocks (99:51) beginning with block 99 
in the bad blocks list. 
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BUFFERSIZE 


BU[FFERSIZE] buffersize 


BUFFERSIZE is a device-dependent parameter command. You use 
BUFFERSIZE to determine the amount of data that IOX transfers for 
every read/write operation request when exercising NFS disks, 
terminals, magnetic tapes, and cassettes. IOX stores the specified 
size in bytes and rounds this number up to the next 4-byte boundary. 


When you use the random data pattern (PATTERN 0), BUFFERSIZE should 
never exceed 3400(decimal) bytes, or IOX generates unpredictable data 
compare errors. 


Although read/write buffers are used for FILES11 disk testing and for 
NFS testing with DECtapes, the buffersize for these devices is fixed. 
A 512(decimal)-byte buffer is used for all FILES11 testing. A 
1024(decimal)-byte buffer is used for all DECtape testing. 


The BUFFERSIZE command is valid only when used by itself in Command 
Mode. In addition, it is valid only if units are not currently 
selected; that is, you must set your default buffer size before you 
select any units for testing. However, you can use the BUFFERSIZE 
command in the SELECT and VERIFY command lines to override the default 
buffer size for the selected device as long as you set the buffer size 
smaller than the default. 


The initial default is 1024(decimal) bytes. The default buffersize 


for terminals is the size of the typeahead buffer, if typeahead is 
enabled. Otherwise, the default is 96(decimal) bytes. 


4-27 
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COMPAREDATA 


COM[PAREDATA] Y[LES]/N[O] 


COMPAREDATA is a device-dependent parameter command for FILES1l1 and 
SELECT that applies to the testing of devices. 


COMPAREDATA enables or disables the checking of the data pattern. 
COMPAREDATA YES enables data pattern checking; COMPAREDATA NO disables 
data pattern checking. When you direct IOX to compare data patterns, 
it compares the data that it writes to the unit with the data it reads 
from the unit. If the data read does not match the data written, IOX 
prints a data compare error report. Section 4.10.2.1 discusses data 
compare error reports in detail. 


You can use COMPAREDATA within the command lines of FILES11 and SELECT 
to override the current COMPAREDATA setting for the device being 
tested. 


The initial default is COMPAREDATA YES. 
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CONFIGURE 


CONF[LIGURE] [dduu:[=type]] .... 


CONFIGURE is a general parameter command and a display command. You 
use CONFIGURE as a parameter command to add devices to your test 
configuration and as a display command to display the current 
configuration. 


IOX configures by default one of each supported device type as unit 
4 9 eae Allowable device types are either DISK, TERM, or TAPE. You can 
add any device to the test configuration to which you can assign a 
logical device name by using the MCR ASN command. When you configure 
a device, IOX adds the device to its list of devices available for 
testing and creates an empty data structure for the device. 


If a device is not already included in the test configuration, you 
must configure it before you can select it for testing. IOX does not 
unconfigure devices at the end of an exercise. Once you have included 
a device in the test configuration, only RESTART will unconfigure it. 


CONFIGURE with no qualifiers displays the current test configuration. 
To find out if a device is already configured, type the following: 


TOX> COMP TGURE 
IOX responds as follows: 
Disks: 
DBO DDO DFO DKO DLO DMO DPO DRO DSO _ DUO 
DXO DYO EMO SyYO 


Tapes: 
CTO DTO MFO MMO MSO MTO MUO 


Terminals: 
TTO 


To add devices to the test configuration, type the following: 
TOAS CONFIGURE DRG? TRIS TRE? XX? YY3 MMS? MOTI =TAPE 


This command line configures devices DK1:, DBl:, DB2:, XX0O:, and YYO: 
as disk units. It configures devices MM5: and MQ]: as tape units. 


You must separate unit specifications with spaces or tabs. 


Use the display form of CONFIGURE to check that these devices have 
been added to your configuration as follows: 


IOX > CONF 

Disks: 

DBO DBl DB2 DDO DFO DKO DKi1 DLO DMO DPO 
DRO DSO DUO DXO DYO EMO SYO xXxXO- yYyYO 


Tapes: 
CTO DTO MFO MMO MM5 MQl MSO MTO MUO 


Terminals: 
TTO 


THE I/O EXERCISER (IOX) 


CONFIGURE (Cont.) 


If you do not specify a device type when you configure a device, the 
device type defaults are as follows: 


l. If one unit of a device type has already been configured as a 
disk and you add a unit with the same device specification, 


IOX also configures that unit as ae disk. For example, 
because DKO: and DBO: in the previous example are 
configured as disks in the default configuration, IOX 


configures DKl:, DBl:, and _ DB2: as disks. By the same 
logic, IOX configures MM5: as a tape because MMO: has been 
configured as a tape unit by default. 


IOX maintains consistency in configuring device units. 
Therefore, you cannot configure DKl:, DBl:, or DB2: as 
tapes. The same holds true for MM5: -- you cannot configure 
it as ae disk. In both cases, IOX generates the following 
error message: 


TORN --  ctetiins? geoodPied device ture is inconsistent 


2. For devices with mnemonics that have not been previously 
configured, the default is disk. Hence, in the following 
example, IOX configures both XX: and YY: as disks, and MQI1: 
as a tape. 


TQXSCONF TRL: NRIs DRS XMt YS MMS 3 MQUS=TAPE 
IOX responds by displaying the following messages: 


TOX ~-- 2xG! deviee ture mob greacified ~- defaulhins to “ISK? 
IQ%¥ -- YG: sevice ture mot seecified ~ defaultinsa to “Ise: 
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CTRL/C 


CTRL/C is a control command. In Command Mode and Interactive Mode, 
CTRL/C generates an MCR prompt "MCR>" allowing you to enter one MCR 
command line. The function of CTRL/C in Execution Mode depends’ on 
whether CONTROL C has been set YES or NO. If you have set CONTROL C 
NO, then CTRL/C generates the MCR prompt "MCR>" as it does in Command 
and Interactive Modes. If you have set CONTROL C YES, then CTRL/C 
exits IOX from Execution Mode and enters Interactive Mode. 


CTRL/C exits to MCR by default in Command and Interactive Modes. In 
Execution Mode, CTRL/C exits Execution Mode and enters Interactive 
Mode by default. 


Section 4.9 describes the three IOX operation modes in detail. 
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CONTROL__C 


CONT[ROL_C] YLES]/N[O] 


CONTROL C is a general parameter command. You use CONTROL _C to enable 
or disable the use of CTRL/C to interrupt an I/O exercise. 


Command Mode 


CTRL/C gives control to MCR for one command line. The CONTROL C 
parameter has no affect on CTRL/C in Command Mode. 


Execution Mode 


If you have set CONTROL _C NO, then CTRL/C gives control to MCR 


and you receive the MCR prompt ">" every time you press the 
RETURN key and "MCR>" every time you press CTRL/C until the 
exercise has terminated. With CTRL/C disabled, you cannot 
interrupt the exercise to enter IOX commands. However, you can 


terminate it with the MCR ABORT command and issue other MCR 
commands while an exercise is in progress. 


If you have set CONTROL C YES, IOX will not accept any input from 
your terminal except CTRL/C. If you try to enter anything but 
CTRL/C, you receive the following error message for each key you 
press: 


TOe «+ flee TP allowes 
When you press CTRL/C, you receive the IOX prompt instead of the 
MCR prompt and IOX exits Execution Mode and enters Interactive 
Mode. 
Interactive Mode 

You have access to Interactive Mode only if CONTROL _C is enabled. 
In Interactive Mode, you can enter most IOX commands. The RETURN 
key and CTRL/C have the same functions in Interactive Mode that 
they have in Command Mode. 


Section 4.9 describes the three IOX operation modes in detail. 


The initial default is CONTROL _C YES. 
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DENSITY 


DEN{SITY] dduu: [n] 2 


DENSITY is a device-dependent parameter command and a display command. 
The DENSITY command applies only to magnetic tape testing and requires 
a magnetic tape device specification for "“dduu:". 


You use DENSITY as a device-dependent parameter command with an 
argument "n" to set the density and characteristic word of a magnetic 
tape. (The device characteristic word is defined in the RSX-11M-PLUS 
Guide to Writing an I/O Driver.) You issue the DENSITY command before 
you select the tape for NFS testing with SELECT. You can also set the 
tape density for a magnetic tape unit by using the DENSITY command 
within the SELECT command line. 


You set all tape densities in bits per inch (bpi) using decimal values 


for "n". The following tape densities are legal: 


MF : MM: MS: MT: MU: 

1600 800 1600 200 1600 

6250 1600 556 6250 
800 


You use DENSITY as a display command without an argument n" to 
display the current density of the specified magnetic tape unit. For 
example: 


IOX>DENSITY MM3 
Tensity= 1600 BFI Characteristic Word= 004004 (octal) 


This command line displays the current density and characteristic word 
for MMO:. To change the tape density to 800, you type the following: 


TOX=DENSITY MM: 800 


The DENSITY command is the only way you can find out what the current 
DENSITY setting is on a magnetic tape (because DENSITY is not 
displayed by the PARAMETERLIST command). 


To display the new tape density and characteristic word for MMO:, you 
type the following: 


TOXSTENSITY MMi 
Yensitv= B00 RFI Characteristic Word= 000000 Cactal) 
For tapes other than MT, MM, MS, MU, and MF, enter the density in 
decimal. However, IOX displays the density in octal as_ the 


characteristic word. For example: 


TOX:0ENS MQ} 
Vensitys PPP? RET Characteristic Ward= 004004 (octal) 


TOXSENS HQ? 800 
LOX=TENS MQ3 
Nensitys PPP? RET Characteristic Word= 001440 (Caoctal) 
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DENSITY (Cont.) 


This command sequence indicates the following: 


IOX does not know the density of the tape designated as MQ:. 
The characteristic word is the default. 


When you set the density of MQ: to 800 bpi (decimal) and 
display the current density and characteristic word, the 
density appears in the characteristic word (octal). 


Except for MT: devices, the initial default density for magnetic tape 
devices is 1600 bpi. The initial default for MT: devices is 800 bpi. 
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DESELECT 


DES[ELECT] ddnn: 

DESELECT is an IOX function command. You use DESELECT to "deselect" 
devices that you have selected for testing with SELECT, VERIFY, or 
FILES11. DESELECT requires device (dd) and unit (nn) specifications. 
If you issue the DESELECT command in Interactive Mode (while testing 
of the specified device is in progress), testing on the device 
terminates and the device is removed from the list of devices to be 
tested. If you issue the command in Command Mode (while no testing is 
in progress), then DESELECT removes the device from the list of 
devices to be tested. 


For devices that you have selected for NFS testing, DESELECT does’ the 
following: 


@ Terminates I/O operations (if they are in progress) 


e Deletes the badblocks list associated with the device (disks 
only) 


e Deallocates all buffer space associated with the device 
@ Detaches IOX from the device 


For devices that you have selected for FILES11 testing, DESELECT does 
the following: 


e Terminates I/O operations (if they are in progress) 
@ Closes and deletes the temporary file 
@e Deallocates all buffer space associated with the device 


The DESELECT command does not remove a device from the test 
configuration. 
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ERRORLIMIT 


ER[LRORLIMIT] n 


ERRORLIMIT is a device-dependent parameter command that sets’ the 
maximum number of errors that I0X will tolerate between interval 
reports, before deselecting a device. 


You use the SUMMARYTIME command to determine how often IOX generates 
interval reports. If you request interval reports every 2 minutes 
(SUMMARYTIME 2) and set ERRORLIMIT at 10 errors, IOX will allow not 
more than 10 errors on a device in a 2-minute interval before 
deselecting the device from testing. 


You can also use the ERRORLIMIT command within the FILES11, SELECT, 
and VERIFY command lines to override the default error limit for the 
device being selected for testing. 


The initial default is 10 errors. 
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EXECUTE 


EXE[CUTE] taskname commandstring 


EXECUTE is a function command. You use EXECUTE to direct a command 
line to the operating system for execution. The task you want to run 
must be installed. For the EXECUTE command to operate, your system 
must support task spawning. The rules for using the SPWNS$ directive 
and entering command lines apply to the arguments for taskname and 
commandstring in the EXECUTE command line (see the RSX-11M/M-PLUS and 
Micro/RSX Executive Reference Manual). 


When you use the EXECUTE command in Interactive Mode (testing in 
progress), the task you have initiated with EXECUTE runs immediately. 
When you use the EXECUTE command in Command Mode (no testing in 
progress), IOX queues the task for execution. The task begins 
executing when you start an exercise with the START command. 


Tasks you initiate with EXECUTE run in parallel with I/0 exercises. 
For example, you use the EXECUTE command to run the BAD utility to 
list at your terminal the bad blocks on an NFS’ disk. You can then 
enter this information in the IOX badblocks list so that IOX will not 
try to perform I/O operations on the blocks that are bad. 


To run the BAD utility on NFS disk DLO:, type the following: 


TOXSEXE ...BA0 ENLOT LG 
In this case, you must include the pound sign (#), as shown in the 
command line. For tasks such as BAD, whose command line processing 
requires a leading space, IOX converts the pound sign to a space. A 


task such as PIP does not require a leading space in its command line. 
For these tasks, you do not need to include the pound sign in the 
command line. 


You can also use the EXECUTE command to run a task to do_ system 
testing while I0X is doing I/O testing. For example, if you have 
written a CPU exerciser task and installed the task as ...QWK, you can 
run this task in parallel with the I/O Exerciser by entering the 
following command line: 


TOME SECUTE 4.-QWK /CPU=1144 
LOX OO START 


where /CPU=1144 is the command line to be passed to task ...QWK. 
To remove a task from the list of tasks to be executed and terminate 


execution of the task (if the task is in progress), you use the ABORT 
command. 
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EXIT 


EXI(T] 


EXIT is a control command. You use the EXIT command to terminate IOX 
processing and exit from IOX to the operating system monitor. 
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FILES11 


FCLilesl1l] dduu: [command=qualifier] ... 


FILES11 is a function command. You use FILES11 to select a Files-1l 
disk for an I/O exercise. Testing a disk with FILES11 protects the 
contents and structure of the disk, because IOX writes into a 
temporary file that IOX removes from the disk at the end of the test. 
You must first configure the disk if it is not already in the test 
configuration before you can select it for testing. 


When you select a disk using FILES11, you can override the default 
parameters by using the following device-dependent parameter commands 
in the FILES11 command line: 


COMPAREDATA 
ERRORLIMIT 
INTERLEAVE 
RANDOM 
TEMPORARYFILE 


The following example uses some of these parameter commands: 


tos PSL ESL GRO? COMPARFIATA=YES RANTOM=NO TEMPORARYFILF=400 


This command line selects DBO: for I/O exercising. IOX compares data 
read with data written, sequentially accesses the blocks in the file, 
and opens a 600-block temporary file. Example 4-1 in Section 4.7 


illustrates and describes how you test an RLO2 with FILES11. 


Once you have selected a device, the default parameters become fixed 
for that device. You cannot reset them without first deselecting the 
device. 


When you issue the FILES11 command in Interactive Mode (while an 
exercise is in progress), IOX begins testing the specified device 
immediately. When you issue the FILES11 command in Command Mode 
(while no exercise is in progress), IOX includes the specified device 
in its list of devices to exercise but does not begin the exercise 
until you start the exercise with the START command. 


If no commands are specified within the FILES11 command line, the 
device is exercised with the default parameters currently in effect. 
Commands can only be separated by spaces or tabs. 
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HELP 


HCELP ] 


HELP is a display command. You type HELP to display a summary of IOX 
commands at your terminal. 
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INTERLEAVE 


ICNTERLEAVE] number 


INTERLEAVE is a parameter command that sets a device-dependent 
parameter for disk testing. The INTERLEAVE command sets the number of 
blocks to be skipped before IOX writes the next buffer of data. The 
INTERLEAVE factor applies only to sequential testing: that is, if you 
have set RANDOM NO. If you have set RANDOM YES, IOX tests blocks’ on 
the disk randomly and ignores the INTERLEAVE factor. The initial 
default. for RANDOM is RANDOM YES. 


You can use the INTERLEAVE command within the FILES11, SELECT, and 
VERIFY command lines to override the current default for the disk 
being selected. 


The initial default is four blocks. 
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LOGFILE 


LCOGFILE] YCES]/N[O] 


LOGFILE is a general parameter command. You use the LOGFILE command 
to direct activity and error reports either to your terminal or toa 
log file in your default disk area. Section 4.10 discusses’ the 
content and format of activity and error reports in detail. 


LOGFILE NO directs activity and error reports to your terminal. 
LOGFILE YES directs activity and error reports’ to the log file. 
Summary reports, which IOX generates when you issue the PRINTSUMMARY 
command, are displayed at your terminal regardless of how you have set 
LOGFILE. 

IOX does not open a new log file each time you run an exercise with 
LOGFILE enabled. Instead, it creates the file when you first run an 


exercise, and then appends to the created file. The file is in your 
area and is named as follows: 


yyyyyy - LOG 


where yyyyyy is the name of the task currently running IOX on _ your 
terminal (IOX, another task name, or the name of your terminal, for 
example TT10). 


In addition to activity and error reports, IOX inserts the following 
date and time information into the log file: 


@e When the exercise began, followed by the output of the 
PARAMETERLIST command 


@ When the exercise ended 

@ When a log file was started 

@ When log file entries were terminated 
@ When an exercise was aborted 


For example, all exercises begin with an event line such as_ the 
following: 


TOX -- 2O-JUL-85 LLt1Sst34 KREAKKRKER EXERCTSER STARTED KEXRHKRKE 
and end with an event line such as: 
TOX -- BOUL BS Lit Par S44 KKKXEKKKK EXPRCISER TERMINATED X¥XKRREX 


The initial default is LOGFILE NO. 
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LOOPBACK 


LCOOPBACK] Y[LES]/N[0O] 


LOOPBACK is a parameter command that is used only for exercising 
terminals. The LOOPBACK command causes IOX to read back ASCII 
characters it has written to a logged-out terminal. To use LOOPBACK, 
you must have installed a loopback connector on the terminal line and 
the terminal line must have typeahead enabled. 


Before using LOOPBACK, certain terminal characteristics must be set. 
These characteristics are SLAVE, PASSTHRU, NOECHO, LOWERCASE, and 
NOWRAP. They must be set BEFORE the loopback connector is installed. 
Typeahead must also be enabled. Since typeahead is required, LOOPBACK 
is available only on systems with the full-duplex terminal driver. 


LOOPBACK is useful for testing a terminal line and interface, since 
characters must be written by the interface to the line, reversed by 
the loopback connector, sent back up the line, received by the 
interface, and read successfully for IOX not to report an error. 
LOOPBACK NO is designed to test a terminal by displaying a portion of 
the ASCII character set. 


LOOPBACK NO is the default. 
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PARAMETERLIST 


PAR[LAMETERLIST] 


PARAMETERLIST is a display command. 


two kinds of information. 
LOX SFARAMETERL IST 
RUFFERSTZFs 


ERRORL IMT Ts 
INTE RLE AVE = 


1024. 
19, 
4, 


PATTERN= @, 
RECORNS= 1024, 
RUNTINE= 3. 


SUMMARYTIME= 1, 
TEMPORARYF ELLE SOO, 


Buffer space usage= 3290.:1924.:1924.:1. 


COMPARE TIATA= 
CONTROL 0 = 
LOGFILE s 
LOOPBACK = 
BAN TOM = 
REFPORTERRORS = 
RE TRI Ss 
VOLUMECHERK = 
WAT Ts 
WRI TR CHEDR = 


PARAMETERLIST displays at 


For example: 


TES 
YES 
NO 

NO 
YFS 
YES 
YES 
YES 
YES 
NO 


@ The current default parameters 


@ I0X buffer space statistics 


At most, 


PARAMETERLIST displays four kinds of information: 


@e Current execution default parameters 


e I10X buffer space statistics 


IOX may also list the: 


e List of tasks initiated by the EXECUTE command 


@ Devices selected for testing with FILES11, 


Example 4-5 describes the 
PARAMETERLIST display 


information. 


that 
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PARAMETERLIST Display Shown in Four Parts 


© 
5) 
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Example 4-5 (Cont.) PARAMETERLIST Display Shown in Four Parts 


Yeyvice Moce KBuffersizve Filesive/Fecards/Ransge Farameters 


TMQ 3 VEY 1O24. 200, - > 12000. RET INT=&, FRR=10, 
MMOS SEL 700. BIOs LOM ERRELO, 
SYS tee wis ROO, COM RFT RAN ERR SO, 


Task Shabus Commend Line re) 
ees RAT QUEUE THO? “LI 


BUPFPFERSIZFE= 1024, COMPARENATA= YES 
ERRORLIMTYT= 10, MPONTRAL = YES 

THERE RAVES 4, LUGE ILE s NO 

PATTERM= @, LOOP GACK= NO 

RECOR(TS= L004, RaNtOM= YRS 1) 
RUNTIME 5. REPORTERRORS= YES 
SUMMARYTIME = 7. RE TRIE Se: TES 

TEMPORARYFELE= 300, VOLUMECHECK = YES 

WAT T= YFS 

WRITECHECK= NO 


Buffer grace ugadas NESR,P1LOSO. TT S88.22. @ 

@ current defaults at the time you entered the PARAMETERLIST 
command. None of the defaults have been changed by the 
command sequence in the example. These are the initial 
default parameters. You can alter the default for these 


parameters. See the description for the appropriate command 
in this section. 


@ IOX buffer space statistics. The form of these statistics 
is the following: 


totalmemory: freeblock:freebytes:fragments 
totalmemory 
Size of IOX buffer space in bytes. 
freeblock 


Size of the largest free block of IOX buffer space in 
bytes. 


freebytes 


Total amount of free bytes available in I0X buffer 
space. 


fragments 
Number of memory fragments in IOX buffer space. 
In the examples, these statistics have changed to reflect 


the buffer allocations for the three devices that you 
selected for testing. 


6 (9 
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® Selected devices and their device-dependent parameters. 
These parameters correspond to the default parameters unless 
you have overridden the defaults in the command line that 
you used to select the devices. 


This part of the display has five fields that are labeled by function. 
They are as follows: 


device 
Device mnemonic of the selected device. 
mode 


Testing mode selected, either VERIFY (VFY), SELECT 
(SEL), or FILES11 (Fll). 


buffersize 


Buffer size used for reading data from the device and 
writing data to the device. You can alter the buffer 


size for magnetic tapes, NFS disks, and cassettes. 
Files-ll disks have a fixed buffer size of 512(decimal) 
bytes. DECtapes have a fixed buffer size of 


1024(decimal) bytes. 
filesize/records/range 
One of the following: 


@e Temporary file size in blocks for disks’ selected 
with FILES11 


e Number of records to test for magnetic tapes and 
cassettes selected with the SELECT command 


@e Range of blocks to be tested on NFS disks that you 
selected with the SELECT or VERIFY command 


parameter 
Device dependent parameters. These either specify a value, 


such as INT=8. or ERR=10. (INTERLEAVE 8 or ERRORLIMIT 10), 
or their presence indicates that you have set a YES/NO 


parameter to YES. For example, in (4) RAN means that you 
set RANDOM YES; and, in (6), the absence of RAN means’ that 
you set RANDOM NO. See Section 4.6 for a list of what 


parameters apply to what devices and modes of testing. 


This display line corresponds to the command line discussed 
next. 


This is the command line that you used to select SY: for 
FILES11 testing, overriding the TEMPORARYFILE and ERRORLIMIT 
defaults. IOX tests SY: as a Files-ll device, using the 
following parameters: 

@e A 512-byte data buffer (fixed) 


e A TEMPORARYFILE size of 800 blocks 
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@ COMPAREDATA enabled (by default) 
e RETRIES enabled (by default) 
@ RANDOM YES (by default) 


e An error limit of 50 errors 


The display line corresponding to the command line discussed 


next. 

The command line you used to select DMO: with VERIFY. IOX 
tests DMO:, using the VERIFY mode with the following 
parameters: 


e The default buffer size of 1024(decimal) bytes 
e The range of blocks 200 through 1000 
@ RETRIES enabled (by default) 
@e RANDOM disabled 
@e The INTERLEAVE factor set to 8 
e The default error limit of 10 
@ The list of tasks initiated by the EXECUTE command 
corresponding to the command line discussed next. 
This part of the display has the following fields: 
e Task Installed -- taskname (...BAD) 


e Status Execution -- status (QUEUED, ACTIVE, SUCCESS, 
WARNING, ERROR, SEVERE ERROR) 


@ Command Line -- line passed to the task 


© The command line you used to execute the BAD utility. 


In Command Mode, you can use CTRL/O to suppress the output of 
PARAMETERLIST. In Interactive Mode, CTRL/O has no affect on the 
output. 
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PATCLTERN] [patternnumber] 


PATTERN is a general parameter command as well as a display command. 
You use PATTERN as a parameter command (with an argument) to set the 
pattern that IOX writes and reads during I/O testing. The PATTERN 
display command (with no argument) displays all 13 patterns and shows 
the pattern that is the current default with an asterisk (*). 


The following example illustrates the default pattern when you use 
PATTERN as a display command: 


TOX= PATTERN 
QO = Random Data * 
= 900090070900000 
= L777779177777 


1 
SF LA25252 7052525 
4 
mt 


~~ 


i 
4 = 1695557132333 
7 = 1631269163126 
6 = G8555S. 155555 
7 @ Oger ees Levee! 


Rie Vie Bow Bae 


Bo= VATA» Taiidi 


9 = 0074177007417 
10 = 0210421071042 
11 = 1042107104210 
12 = 052652052652 


To change the default pattern from random data to “125252,052525", 
which is pattern 3, you type: 


TOX=FATTERN 3 


Using the display form of PATTERN now shows that the asterisk moved 
from pattern 0 to pattern 3 after you changed the default: 


TOXSPATTERN 


0 Random ate 

1 = 0000007000006 

ae au 0 or AF oF er ae a at ae oe a 
Zo= (PSSHSPORPHLS 


4 © 1655559133333 
§ = 1631267163126 
4 = O5955557155555 
7 O222229 122222 
8 = ALLL 111111 
¥ = 0674177007417 
190 = O3190427990219042 
ti = 1042107104210 


12 = OF 26529052652 


The form of the PATTERN command that changes the pattern default is 
valid only in Command Mode. 


Pattern O is random data from pure portions of the I/O Exerciser 
itself. When you use the random data pattern, the buffer size should 
never exceed 3400(decimal) bytes or IOX will generate unpredictable 
data compare errors. 


The initial default pattern is random data, pattern 0. 
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PRI[NTSUMMARY ] 


PRINTSUMMARY is a display command that is valid only in Interactive 
Mode. 


IOX outputs activity reports and error reports. Activity reports 
summarize IOX processing information, such as how long an exercise 
will run and how many ASTs have been executed. There are three kinds 
of activity reports: accumulated totals, interval reports, and 
summary reports. (For a complete description of these three kinds of 
activity reports, see Section 4.10.) 


Summary reports and interval reports have the same content and format. 
However, IOX generates interval reports at the time intervals that you 
have set with the SUMMARYTIME command. IOX generates summary reports 
when you enter the PRINTSUMMARY command in Interactive Mode. A 
summary report summarizes IOX activity between the last interval 
report and the time you enter the PRINTSUMMARY command. I0OX displays 
summary reports at your terminal even if LOGFILE is enabled. 


THE I/O EXERCISER (IOX) 
PROCEED 


PRO[CEED] 


PROCEED is a control command that you use only in Interactive Mode. 
(Section 4.9 describes the three IOX operating modes in detail.) When 
you enter the PROCEED command, IOX exits Interactive Mode, enters 
Execution Mode, and checks for IOX activity. If no exercises are in 
progress and no tasks initiated by IOX are executing, then I0OX 
terminates the exercise. 


If there is activity, IOX resumes display of activity and error 
reports to your terminal if you have set LOGFILE NO. (With LOGFILE 
disabled, IOX suspends activity and error reports to your terminal in 
Interactive Mode. With LOGFILE enabled, IOX continues recording 
activity and error reports in the log file.) 


Use the PROCEED command only if you want IOX to terminate an exercise 
as soon as activity terminates, or if you want IOX to resume display 
of activity and error reports at your terminal with LOGFILE disabled. 
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RANDOM 


RAND[OM] YLES]/N[O] 


RANDOM is a device-dependent parameter command that applies to disk 
testing. The RANDOM command directs IOX to select either random or 
sequential blocks for disk testing. 


RANDOM YES directs IOX to use its random number generator to choose 
the blocks on the selected disk for exercising. RANDOM NO directs IOX 
to sequentially test blocks on the disk. 


If you set RANDOM NO, IOX skips the number of blocks specified with 
the INTERLEAVE command before testing the next block. For example: 


LOS INTERLEAYVE & 

LOS oR ATTA NO 
In this example, IOX tests every eighth block on the disk (that is, 
block O, 7, 15, . . . é Ji 


You can use the RANDOM command within the FILES11, SELECT, and VERIFY 
command lines to override the current default parameter, when 
selecting blocks for testing. 


The initial default is RANDOM YES. 
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RANGE 


RANG[LE] dduu: [minimum:maximum] 


RANGE is a device-dependent parameter command and a display command. 
The RANGE command applies only to disks that you have selected for NFS 
testing with SELECT or VERIFY. 


RANGE, as a parameter command, sets the minimum and maximum block 
numbers for NFS testing on the specified disk unit. For example: 


[aX oRARTE THOS ZoQTsOS 


IOX tests blocks in the range 300 through 500 on DLO. This form of 
the RANGE command can be used in the SELECT or VERIFY command lines to 
specify the range of blocks to be tested. 


RANGE, as a display command, displays the current range of blocks’ to 
be tested on the specified disk unit. The device must have been 
selected for testing. 


For example: 


TOXSRARGE ROS 
Dp oth S 24s 420, 
This is the default for RLO2 devices. After you issue the RANGE 


command in the previous example, you can use the RANGE command to 
display the current range of blocks to be tested as follows: 


TOX¥ERANKE TO? 
S00 OSs BOs 


This form of the RANGE command cannot be used within the SELECT or 
VERIFY command lines. 


The default range for all disks that have been selected is zero to the 
maximum block number on the disk minus sixty (O:maximum-60). 
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RECORDS 


REC[LORDS] recordcount 


RECORDS is a device-dependent parameter command that applies to _ the 
testing of magnetic tapes and cassettes with SELECT. RECORDS 
specifies a record count, which is the number of records on the 
magnetic tape or cassette to be exercised. For example: 


TOXSRECORDS 206 


This command line directs IOX to exercise 200 records on all magnetic 
tapes and cassettes. RECORDS O directs IOX to test the records on 
magnetic tapes and cassettes until it detects the end of the tape, at 
which time IOX displays an end of tape message and deselects the tape 
unit. 


You can use RECORDS in the SELECT command line to override the default 
recordcount for the magnetic tape or cassette being selected. 


The initial default is 1024(decimal) records. 
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REPORTERRORS 


REP[LORTERRORS] Y[LES]/N[O] 


REPORTERRORS is a general parameter command that you use to enable 
(REPORTERRORS YES) or disable (REPORTERRORS NO) IOX error reports. 
There are two kinds of error reports: data compare error reports’ and 
I/O error reports. 


If a success code is returned from the device driver (meaning that a 
QIO succeeded), but the data that IOX wrote does not match the data 
that IOX read, then a data compare error has occurred. Section 
4.10.2.1 illustrates and describes data compare error reports. 


I/O error codes are returned from the device drivers (meaning that a 
QIO failed). These error codes generate one of 12 error messages 
discussed in Sections 4.10 and 4.13. 


IOX directs error reports to your terminal, but with the following 
restrictions: 


@ Error reports never interrupt activity reports. 


e If LOGFILE is enabled, IOX enters error reports in the _ log 
file instead of displaying them at your terminal. 


@e In Interactive Mode, IOX suppresses the printing of error 
reports. 


The initial default is REPORTERRORS YES. 
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RESTART 


RES[TART ] 
RESTART is a control command. The RESTART command is valid only in 
Command Mode. When you restart the I/O Exerciser, you effectively 
reinvoke IOX without exiting to the operating system monitor. 
The RESTART command performs the following functions: 

e Deselects devices that are selected for testing 


e Resets all parameters to their initial defaults 


@ Removes all tasks queued for execution by the EXECUTE command 
from the list of tasks to be executed 


e Unconfigures all devices that you added to the default 
configuration 
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RETRIES 


RETCRIES] Y{ES]/N[O] 


RETRIES is a device-dependent parameter command that applies to the 
testing of magnetic tapes and NFS disks. RETRIES YES directs a device 
driver to use its standard recovery techniques to attempt to recover 
from an error. RETRIES NO inhibits an I/O driver from using its 
standard recovery techniques when it encounters an error. 


You can use the RETRIES command within the SELECT and VERIFY command 
lines to override the current default for the device being selected. 


The initial default is RETRIES YES. 
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RUNTIME 


RUN[TIME] minutes 


RUNTIME is a general parameter command. Note that RUNTIME is’ valid 
only in Command Mode, when no exercising is in progress. 


You use the RUNTIME command to specify how many minutes you want I0OX 
to test the devices(s) that you have selected for testing. If you 
specify RUNTIME 0, IOX continues testing the selected devices until 
you abort the exercise with either the IOX ABORT command or the MCR 
ABORT command. 


The initial default is 5 minutes. 
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SELECT 


SE[CLECT] dduu: [command=qualifier] .... 


SELECT is a function command. The SELECT command selects a device 
with an NFS volume mounted for an I/O exercise that destroys the 
contents and structure of the volume. Before using SELECT, you must 
first configure the device if it is not in the test configuration. 


When you use the SELECT command to select a device to be tested as an 
NFS volume, you can override the current default parameters by using 
the commands in Table 4-3 within the SELECT command line. 


Table 4-3 
Parameter Commands by Device Type for the SELECT Command 


NFS Disks Cassettes DECtapes Magnetic Terminals 
Tapes 

BUFFERSIZE BUFFERSIZE COMPAREDATA BUFFERSIZE BUFFERSIZE 
COMPAREDATA COMPAREDATA ERRORLIMIT ERRORLIMIT COMPAREDATA 
ERRORLIMIT ERRORLIMIT DENSITY ERRORLIMIT 
INTERLEAVE RECORDS RECORDS LOOPBACK 
RANDOM RETRIES 

RANGE 

RETRIES 
VOLUMECHECK 
WRITECHECK 


The following command line illustrates some of these commands: 
TOXS GFL TL O% RANG=10054000 RET=YES RANTIZENO INT=8 RUF =2006 
This command line does the following: 
e Selects DLO: for I/O exercising 
e Tests only blocks 100 through 4000 


e Allows the driver to retry I/O operations if it encounters 
errors 


e Accesses the blocks on the volume sequentially testing every 
eighth block 


@ Uses a data buffer of 2000 bytes for data transfer 


Once you have selected a device, the default parameters become fixed 
for that device. You cannot reset them without first "deselecting" 
the device. 


When you issue the SELECT command in Interactive Mode (while an 
exercise is in progress), IOX begins testing the specified device 
immediately. When you issue the SELECT command in Command Mode (while 
no exercise is in progress), IOX includes the specified device in its 
list of devices to exercise but does not begin the exercise until you 
start the exercise with the START command. 
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SELECT (Cont.) 


If no further parameter commands are specified within the SELECT 
command line, the device is exercised with the parameters currently in 
effect. Note that commands can be separated only by spaces or tabs. 


Example 4-2 in Section 4.8.1 illustrates and describes how you test a 
magnetic tape unit with the SELECT command. 
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SPY 


SPLY] [dduu:] 
SPY is a display command. You use the SPY command only in Interactive 
Mode (exercising in progress) to display status information on 
device(s) being tested. 
If you do not specify an argument with SPY, you will receive a display 
of status information on all devices being tested. When specified 
with a device and unit specification, SPY displays status information 
only for the specified device. For example: 

“SPY TRO? 
IOX outputs the following: 

HEQs (== TYPESELI VRN= SOS. T/0=AST Quened FUNCTION=WRI TE 
This output indicates the following: 


@ Device being exercised (DBO:) 


e Type of testing being performed on the device: FILES11 (F1l), 
SELECT (SEL), VERIFY (VFY) 


e Virtual block number being tested (305(decimal) in this 
example), or, for NFS volumes, the logical block number 


e I/O request status: AST queued, in progress, or idle 
@e Type of I/O function being performed: READ or WRITE 


SPY always outputs to your terminal, even if LOGFILE is enabled. 
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START 


STCART] 


START is a control command and is valid only in Command Mode. When 
you use the START command, IOX exits Command Mode and enters Execution 
Mode. Section 4.9 discusses the three IOX operating modes in detail. 


After you have set your test configuration and selected the devices 
you want to test, use the START command to begin exercising the 
selected units. START also turns on the IOX clock, begins activity 
and error reporting (if you enabled error reporting with REPORTERRORS 
YES), and begins executing tasks queued by the EXECUTE command. 
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SUMMARYTIME 


SULMMARYTIME] minutes 


SUMMARYTIME is a general parameter command that you use to specify how 
often (in minutes) IOX outputs interval reports. (See Section 4.10 
for a complete discussion of interval reports). You can suppress 
interval reports by setting SUMMARYTIME to 0. 


The initial default is 1 minute. 


THE 1/0 EXERCISER (IOX) 


TEMPORARYFILE 


TCEMPORARYFILE] filesize 


TEMPORARYFILE is a device-dependent parameter command that applies to 
the testing of Files-ll disks with the FILES11 command. The FILES11 
command protects the contents of the disk by writing them to a 
temporary file, which IOX deletes at the end of the exercise. You 
specify the file size in blocks. 


You can use the TEMPORARYFILE command in the FILES11 command line to 
override the current default for the disk being selected. 


The initial default is 500 blocks. 
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VERIFY 


VECRIFY] dduu: f[command=qualifier] .... 


VERIFY is a function command you use to select a mounted NFS disk for 
an exercise. VERIFY reads buffers of data without: writing on the 
disk, performing data comparisons, or destroying the contents of the 
disk. 


VERIFY accepts the following device-dependent parameter commands 
within its command line to override the default parameters for the 
device being tested: 


BUFFERSIZE 
ERRORLIMIT 
INTERLEAVE 
RANDOM 
RANGE 
RETRIES 


The following example illustrates how you use the ERRORLIMIT and RANGE 
commands within the VERIFY command line to override the current 
defaults for testing DMO: 


TOXSVERR TRY THO? RANGE LOG07 4900 FERRARLIMTT= G00 


This command line selects DMO: for read only testing of blocks 1000 
through 3000 (inclusive) with a maximum of 1000 errors before IOX 
deselects the disk. 


Once you have selected a device, the default parameters for that 
device are fixed. You cannot reset them without first deselecting the 
device. 


When you use the VERIFY command in Interactive Mode (while an exercise 
is in progress), IOX begins testing the specified device immediately. 
When you issue the VERIFY command in Command Mode (while no exercise 
is in progress), IOX includes the specified device in its list of 
devices to exercise but does not begin the exercise until you start 
the exercise with the START command. 


If no further parameter commands are specified within the VERIFY 
command line, the disk is exercised with the parameters currently in 
effect. Commands can only be separated by spaces or tabs. 


Example 4-3 in Section 4.8.2 illustrates and explains how you test an 
NFS disk with VERIFY. 


THE I/O EXERCISER (I0X) 


VOLUMECHECK 


VO[CLUMECHECK] Y[ES]/N[O] 


VOLUMECHECK is a device-dependent parameter command that applies to 
NFS disk testing with SELECT. VOLUMECHECK enables or disables 
checking of disks mounted as NFS volumes for a home block and a 
Files-ll structure. If VOLUMECHECK is enabled (VOLUMECHECK YES), IOX 
will not allow you to use the SELECT command to select a volume with a 
Files-1ll structure. With VOLUMECHECK disabled (VOLUMECHECK NO), IOX 
will allow you to use the SELECT command to select the disk without 
warning you that the test will destroy the contents of the disk. You 
should use VOLUMECHECK YES unless you are intentionally writing over a 
Files-1ll disk. 


You can use the VOLUMECHECK command within the SELECT command line to 
override the current default values for the disk being selected. 


The initial default is VOLUMECHECK YES. 
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WAIT 


WALIT] YCES]/N[O] 


WAIT is a general parameter command you use to determine whether or 
not IOX waits for an event flag while an exercise is in progress. The 


WAIT command has no effect on tasks initiated with the EXECUTE 
command. 


WAIT YES requires IOX to wait for an event flag to signal that an I/O 


operation has completed. During this time, the Executive may be able 
to execute another task. 


If you set WAIT NO, IOX executes an idle loop during I/O operations. 
Setting WAIT NO can monopolize system resources. Therefore, you 


should not set WAIT NO unless you intentionally want to monopolize 
system resources. 


The initial default is WAIT YES. 
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WRITECHECK 


WRLITECHECK] Y[LES]/N[O] 


WRITECHECK is a device-dependent parameter command that applies only 
to testing NFS disks with SELECT. You use the WRITECHECK command to 
determine whether or not I/O drivers perform write checks to NFS 
disks. 


If WRITECHECK is enabled, IOX writes data to the disks by issuing an 
IO.WLC (write logical block with check) to the driver instead of 


IO.WLB (write logical block). The disk controller reads, 
word-by-word, a copy of the data from the data buffer, while 
simultaneously reading the same data from the disk. The disk 


controller compares the two copies of the data. If the copies do not 
match, and if RETRIES is enabled, the driver repeats the original 
write operation and performs another write check. This process 
continues until the WRITECHECK function succeeds or the retry count 
for the driver is exceeded. If RETRIES is disabled or if RETRIES is 
enabled but the retry count for the driver is exceeded, the driver 
issues the "hard" error message, IE.WCK, and IOX generates an error 
message. 


You can use the WRITECHECK command within the SELECT command line to 
override the current default for the device being selected. 


The initial default is WRITECHECK NO. 
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4.13 ERROR MESSAGES 


IOX generates two types of error messages: error messages with device 
specifications and error messages without device specifications. IOX 
displays device specifications as appropriate. 


The format for an error message with a device specification is as 
follows: 


taskname -- ddnn: message 
taskname 
Name of the IOX task that is currently running. In the error 


messages that follow, taskname is always IOX. 
ddnn 

Device specification text of the message. 
message 

Information specific to this message. 


The format for an error message without a device specification is as 
follows: 


taskname-~message 


where taskname and message are the same as defined in the previous 
format. 


All error messages use the letter "x" to indicate that IOX substitutes 


the appropriate command, task name, or value for "x" within the 
message. 


4.13.1 Error Messages with Device Specifications 


The error messages are presented in alphabetical order by the first 
letter following the device specification. 


IOX -- dduu: bad block, xxx (decimal) xxx (octal) 


Explanation: IE.BBE error code returned to I0X (bad _ block 
error). 


User Action: Use the BADBLOCKS command (only for NFS disks) to 
enter the block number into the bad blocks list. 


IOX -- dduu: block number out of range 


Explanation: You used the BADBLOCKS command to enter a block 
number in the bad blocks list that is outside the range of blocks 
that you specified with the RANGE command. 
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IOX -- TTuu: buffer size being reduced to typeahead buffer size 


Explanation: The buffer size specified or used by default is 
larger than the size of the typeahead buffer. 


User Action: None. IOX will reduce the buffer size to equal the 
size of the typeahead buffer. 


IOX -- dduu: buffer size is greater than default 


Explanation: The buffer size that you specified in the SELECT or 
VERIFY command line is greater than the current default set with 
the BUFFERSIZE command by itself. 


User Action: Either raise the default buffer size (using 
BUFFERSIZE by itself) or lower the buffer size override for the 
device (using BUFFERSIZE within the SELECT or VERIFY command 
line). 


IOX -- dduu: data compare error at block xxx (decimal) xxx (octal) 


Good data: xxxxx bad data: xxxxx 
Word position: xxx (decimal) xxx (octal) 
Buffer contained xx. additional errors 


Explanation: IOX found an error when comparing the data read 
with the data written. This error message shows the first block 
number in which the error occurred during the transfer, the good 
and bad data, the word position of the first error found in the 
buffer, and the number of additional errors found in the buffer. 
Section 4.10.2.1 discusses data compare error reports in detail. 


User Action: None. If the error persists, enter the block in 
the bad blocks list by using the BADBLOCKS command (for NFS disks 
only). 


IOX -- dduu: data overrun at block xxx (decimal) xxx (octal) 


Explanation: IE.DAO error code returned to IOX (data overrun). 
The record size given was greater than the record size read. 
This error occurs on tape devices only. 


User Action: None. 


IOX -- dduu: device type not specified - defaulting to 'DISK' 
Explanation: This message tells you that you are adding a device 
to your test configuration with the CONFIGURE command and that 
IOX is configuring that device as a disk by default. 

User Action: None. 

IOX -- dduu: did not respond - unit now deselected 
Explanation: The unit did not respond to the IOX command within 
1 minute. The device may have been accidentally put off line or 


a tape drive may have lost its column vacuum. 


User Action: Check the device. 


TOX 


IOX 


IOX 


IOX 


IOX 


IOX 


IOX 
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-- TTuu: does not support the LOOPBACK command 

Explanation: LOOPBACK cannot be used with the selected terminal 
line. This is because of insufficient support in the terminal 
driver (LOOPBACK is supported only with the full-duplex terminal 
driver) or because typeahead is disabled. 

User Action: For full-duplex terminal driver systems, enable 
typeahead. 


-- dduu: does not support the x command 


Explanation: The x command is incompatible with the device 
specification, dduu:. 


User Action: None. 


-~- dduu: duplicate block number 


Explanation: The block number you entered with the BADBLOCKS 
command is already in the bad blocks list for the device. 


User Action: None. 


-- dduu: end of tape detected - unit now deselected 

Explanation: I0.EOT error code returned to IOX (end-of-tape 
detected). IOX attempted to write a record past the end-of-tape 
marker. 


User Action: This is an informational message only. 


-- dduu: error threshold exceeded - unit now deselected 


Explanation: The number of errors set with the ERRORLIMIT 
command has been exceeded. 


User Action: None. 


-- dduu: error while reading home block 

Explanation: When VOLUMECHECK is enabled, this message occurs if 
IOX detects an error while attempting to read the home block of a 
Files-1l device. 

User Action: The disk you selected may be defective. If you are 
testing a scratch disk, select the disk again with VOLUMECHECK 
NO. 
-- dduu: failed to attach 

Explanation: IOX could not attach the unit. 


User Action: The device may be mounted or attached by someone 
else. Make sure you have allocated and mounted the device. 


For RSX11M-PLUS systems, mount devices with the /FOREIGN switch. 
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IOX 


IOX 


IOX 
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-- dduu: failed to detach 


Explanation: An error occurred while IOX was attempting to 
detach a unit that it had previously attached. 


User Action: None. This is a possible operating system problem. 


-- dduu: failed to open temporary file 

Explanation: IOX could not find enough free blocks on the disk 
to open a temporary file as large as the one you specified with 
the TEMPORARYFILE command. 

User Action: Specify a smaller temporary file size either by 
resetting the default with the TEMPORARYFILE command or by using 
TEMPORARYFILE within the FILES11 command line to override the 
default TEMPORARYFILE size for each device. 

If you are using the default (500 blocks) when IOX generates this 
message, you need to make room on the disk. 


-- dduu: fatal hardware error - unit now deselected 


Explanation: IE.FHE error code returned to IOX (fatal hardware 
error). 


User Action: Check the hardware. 


-- dduu: illegal density 


Explanation: The density that you specified with the DENSITY 
command, for the magnetic tape is illegal. 


User Action: Reenter the command, using a legal density. See 
Section 4.12. 
-~- dduu: illegal range 


Explanation: The range of blocks which you specified on the 
device to be tested with the RANGE command is out of bounds. 


User Action: Use RANGE with no qualifier to check the default 
range on the device; then specify a range within bounds. 
-- dduu: invalid block number 


Explanation: The block number that you’ entered with the 
BADBLOCKS command was not a valid block number for the device. 


User Action: None. 


-- dduu: I/O is unsatisfied at timeout - function: xxxx 
Explanation: When IOX finishes processing, it waits 5 seconds 
for 1/0 to stop. If a long tape has not finished rewinding, this 
message may occur. The function that timed out is xxxx. 


User Action: None. 
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IOX 


IOX 


IOX 
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-- dduu: I/O request aborted - unit now deselected 


Explanation: IE.ABO error code returned to I0OX (operation 
aborted). 


User Action: None. 


-~ dduu: is already configured 


Explanation: You tried to configure with the CONFIGURE command a 
unit that is already in the test configuration. 


User Action: Use the CONFIGURE command as a display command to 
check which devices are configured. 
-- dduu: is already selected 


Explanation: You tried to select a unit that has already been 
selected. 


User Action: Use the PARAMETERLIST command to display 
information on all units that are selected. 
-- TTuu: is logged in 

Explanation: A user is logged in on the terminal selected. 


User Action: Select a terminal line that is not in use. 


-- dduu: is not configured 


Explanation: You issued a command that is valid only for 
configured devices. 


User Action: Use the CONFIGURE command to configure the device. 


-- dduu: is not mounted or allocated for NFS operations 
Explanation: You have selected a device for testing with SELECT 
or VERIFY that is not properly allocated and mounted for NFS 
testing. 

User Action: Allocate and mount the device. 
For RSX1LIM-PLUS systems, mount NFS devices with the /FOREIGN 
switch. 


-- dduu: is not ready - unit now deselected 


Explanation: IE.DNR error code returned to I0X (device not 
ready). 


User Action: Select the device again. 
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IOX -- dduu: is not selected 
Explanation: You issued a device-dependent parameter command 
(BADBLOCKS or RANGE) that is valid only after you have selected 
the device. 


User Action: Select the device; then reenter the command. 


IOX -- dduu: is offline 
Explanation: IE.OFL error code returned to IOX (device off 
line). The device was taken off line while testing was in 
progress, or you tried to select a device that was off line. If 
testing was in progress on the device when it was taken off line, 
IOX appends " - unit now deselected" to the error message. 


User Action: Ensure that the device is on line. 


IOX -- dduu: is write locked - unit now deselected 


Explanation: IE.WLK error code returned to I0X (write-lock 
error). The device is write-locked. 


User Action: Check the device write-lock/write-enable switch and 
the MCR write-lock status. 


IOX -- dduu: LUN assignment failure 


Explanation: This probably means that the device, ddnn:, is not 
physically present in your system. It may also mean that you 
have exceeded the number of devices that IOX can _ support. The 
default is 28 devices; the maximum number of devices is 246. 


User Action: If the device is not physically present in your 
system then take no action. If you have exceeded the number of 
devices that IOX can support, then edit the Task Builder command 
file, IOXBLD.CMD (see Section 4.11), to allow IOX to support more 


devices. 

IOX -- dduu: privilege violation - unit now deselected 
Explanation: IE.PRI error code returned to I0X (privilege 
violation). The device was not allocated or it was mounted by 


someone else. 


User Action: Check the ownership of the device. 


IOX -- dduu: specified device type is inconsistent 


Explanation: You tried to configure device "dduu" as a tape when 
a "dd" device had already been configured as a disk. The same 
holds true if "dd" had already been configured as a tape and you 
tried to configure another "dd" device as a disk. 


User Action: Use the CONFIGURE command as a display command to 
check on the devices in your test configuration. Configure the 
unit using a different device mnemonic. 
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IOX -- dduu: unexpected error #xx 


Explanation: IOX received an I/O error code that it could not 
process. The error code is xx (octal). 


User Action: None. 


IOX -- dduu: unexpected request to queue I/O - request aborted 


Explanation: IOX received an AST from a device after it had 
deselected the device. 


User Action: Check the device. 


IOX -~ dduu: unrecoverable error at block xxx (decimal) xxx (octal) 


Explanation: IE.VER error code returned to I0X (unrecoverable 
error). This code indicates an unrecoverable error. 


User Action: Check the device and media. 


IOX -- dduu: VOLUMECHECK failure. Unit contains a home block 

Explanation: The unit is file-structured because the device 
contains a home block. This error message is generated by select 
if you try to select a Files-1ll volume while VOLUMECHECK is 
enabled. 
User Action: I0X destroys information on devices that you select 
for exercising with the SELECT command. If you want to destroy 
the contents of the disk, disable VOLUMECHECK (VOLUMECHECK NO) 
and select the device again. 


IOX -- dduu: write check error at block xxx (decimal) xxx (octal) 


Explanation: IE.WCK error code returned to I0OX (write check 
error). The write check operation failed at block xxx. 


User Action: None. 


4.13.2 Error Messages Without Device Specifications 
These error messages are presented in alphabetical order by the first 
letter following the IOX task name. 
IOX -- Indirect command file syntax error 
Explanation: There is an error in the indirect command file. 


User Action: Check the indirect command file. 


IOX -- Indirect command file nesting level exceeded 


Explanation: IOX accepts indirect command files with only one 
level of nesting. 


User Action: Rewrite the indirect command file so that it does 
not have more than one level of nesting. 
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-- Aborting due to user command 
Explanation: You aborted IOX by using the MCR ABORT command. 


User Action: Reinvoke IOX if you want to continue testing. 


-- EXECUTE command is not supported 


Explanation: You attempted to use the EXECUTE command in a 
system that does not support task spawning. 


User Action: Do another SYSGEN if you require the EXECUTE 
command to properly test your I/O devices. 
-- Command input I/O error 


Explanation: IOX detected an error when it tried to read _ the 
command that you typed at the terminal. 


User Action: Reenter the command. 


- Command valid only in Command Mode 


Explanation: You tried to enter a command that cannot be entered 
while an I/O exercise is in progress. 


User Action: Either abort the exercise and enter the command or 
walt until the exercise has finished to enter the command. 
-- Command valid only in Interactive Mode 


Explanation: You tried to enter a command that cannot be entered 
unless IOX is running. 


User Action: Type START; then reenter the command. 


-- Command not unique 


Explanation: The command abbreviation that you entered did not 
distinguish it from another command. 


User Action: Reenter the command by using a longer abbreviation. 


-- Failed to close log file. F.ERR= -x 


Explanation: IOX could not close the log file in your directory. 
The FCS error returned was "-x". 


User Action: Look up the I/O error code returned to IOX by FCS 
in the RSX-11M/M-PLUS and Micro/RSX I/O Operations Reference 
Manual and take the appropriate action. 


-- Failed to open indirect command file 


Explanation: The FCS GCML routine failed to open the indirect 
command file. 


User Action: Check to see that the file exists and that you 
specified the file correctly; then resubmit the file to IOX. 
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IOX -- Failed to open log file. F.ERR= -x 


Explanation: IOX could not open the log file. The FCS error 


returned was "-x". 


User Action: The disk may be write protected or may not have 
enough blocks. 


IOX -- Failed to open existing log file. F.ERR= -x 


Explanation: IOX could not open a log file that already exists 
in your directory. The FCS error returned was "-x". 


User Action: Look up the I/O error code returned to IOX by FCS 
in the RSX-11M/M-PLUS and Micro/RSX I/O Operations Reference 
Manual and take the appropriate action. 


IOX -- Failed to truncate/close log file. F.ERR= -x 


Explanation: IOX could not truncate or close the log file. The 
FCS error returned was "-x". 

User Action: Look up the I/O error code returned to IOX by FCS 
in the RSX-11M/M-PLUS and Micro/RSX I/O Operations Reference 
Manual and take the appropriate action. 


IOX -- Fatal file system error. F.ERR= xxx PC+2= xxx 


Explanation: I0OX exited because an error occurred while IOX was 
trying to issue a read or write. F.ERR is the octal error code 
in the File Descriptor Block indicating the kind of file error. 
PC+2 is the octal location of the failure in the IOX code. 


User Action: Look up the I/O error code returned to IOX by FCS 
in the RSX-11M/M-PLUS and Micro/RSX I/O Operations Reference 
Manual and take the appropriate action. 


IOX -- Fatal system error. DSW= xxx PC+2= xxx 


Explanation: IOX immediately exits because a directive that IOX 
issued failed. DSW is the Directive Status word in octal. PC+2 
is the octal location of the failure in the IOX code. 


User Action: Look up the I/O error code returned to IOX by FCS 
in the RSX-11M/M-PLUS and Micro/RSX Executive Reference Manual 


and take the appropriate action. 


IOX -- Invalid pattern number 
Explanation: You tried to set a data pattern using a pattern 
number greater than 12. The valid arguments for PATTERN are 0 
through 12. 


User Action: Enter a valid pattern number. 
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-- Invalid task name 

Explanation: The task name that you specified with the EXECUTE 
command is invalid. The task name is either incorrect or the 
task does not exist. 

User Action: Reenter the task name correctly or determine if the 
task exists. 
-- No activity remains - aborting 

Explanation: In Execution Mode, IOX determines whether or not 
any exercises are in progress or any tasks are executing at one 
minute intervals. If IOX finds no activity, it aborts’ the 
exercise and generates this informational message. 

In Interactive Mode, IOX determines whether or not any exercises 
are in progress or any tasks are executing only when you enter 
the PROCEED command. If there is no activity when you enter 
PROCEED, IOX aborts the exercise and issues this informational 
message. 


User Action: None. 


-- No activity to start 


Explanation: When you issued the START command, no devices were 
selected for testing and no tasks were initiated for execution. 


User Action: Select devices that you want to test, and use _ the 
EXECUTE command to initiate tasks that you want to execute. 
-- No buffer space available 


Explanation: IOX does not have adequate buffer space to 
accommodate all the devices you selected. 


User Action: Either deselect some devices from testing or 
reinstall or reinvoke IOX with a greater increment. 

-- No such command - type H for help 

Explanation: You entered a command that IOX did not recognize. 
User Action: Type H (abbreviation for the HELP command), which 
displays a summary all IOX commands. 

-- No tasks to abort 


Explanation: You tried to abort tasks using the ABORT command 
when no tasks had been initiated by the EXECUTE command. 


User Action: None. 
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-~- Only CTRL/C allowed 

Explanation: You set CONTROL C YES to enable you to enter I0X 
commands while exercises are in progress. Therefore, IOX only 
accepts CTRL/C in Execution Mode. 

User Action: Enter CTRL/C to exit Execution Mode, then IOX is in 
Interactive Mode and you can enter commands. 


-- Syntax error 


Explanation: The command line that you entered contained a 
syntax error. 


User Action: If necessary, check the syntax of the command line 
that you entered. See Section 4.12 or type H (for HELP). 
-- Task never executed 


Explanation: The task that you tried to abort is not on the list 
of tasks initiated by the EXECUTE command. 


User Action: Use the PARAMETERLIST command to check the list of 
tasks to be executed. 
-- Task "“xxxxxx" is currently active 


Explanation: You tried to execute a task that was already 
active. The name of the task is "xxxxxx". 


User Action: None. 


-- Task "xxxxxx" is completed. Status= nnnnnnn 

Explanation: The task has completed execution. The name of the 
task is "xxxxxx". There are four task statuses represented by 
“nnnnnnn": SUCCESS, WARNING, ERROR, and SEVERE ERROR. 


User Action: None. 


-- Task "xxxxxx" is not installed 


Explanation: Task "“xxxxxx" is not installed and cannot be 
initiated using the EXECUTE command. 


User Action: Install the task from a privileged terminal. 


-- Task "xxxxxx" is unable to execute 
Explanation: Task "xxxxxx" could not execute. 


User Action: Try to execute the task again. 
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IOX -- Units are selected - command ignored 


Explanation: The BUFFERSIZE command is valid only if no _ units 
are selected for testing. 


User Action: You can use the BUFFERSIZE command within the 
SELECT and VERIFY command lines to override the default for each 
device. However, if you require a larger buffer size for all 
devices, use the DESELECT command to deselect all units; then 
reissue the BUFFERSIZE command. 
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THE BAD BLOCK REPLACEMENT CONTROL TASK (RCT) 


The Bad Block Replacement Control Task (RCT) handles bad block 
replacement and recovery on Mass Storage Control Protocol (MSCP) disks 
such as the RA80. Bad block handling on MSCP disks consists of four 
stages: 


1. Detecting 

2. Notifying 

3. Replacing 

4. Revectoring 
The disk controller (UDA50) handles the detection of bad blocks and 
notification of the driver (DUDRV). The driver activates RCT. RCT 
performs all the bad block replacement functions that enable the 
controller to revector (redirect) I/O from the _ bad block to the 
replacement block. 
RCT also performs replacement and recovery on MSCP disks that went off 


line during bad block replacement or before the contents of a 
write-back cache were copied to the disk. 


5.1 BAD BLOCK REPLACEMENT FUNCTIONS 

RCT performs the following bad block replacement functions: 
e Stores data from the bad block 
e Allocates a replacement block 
@ Updates data structures on the disk 


e Initializes the replacement block 


5.2 RECOVERY TECHNIQUES 


RCT checks MSCP disks that have just come on line for two conditions: 
incomplete bad block replacement, and write-back cache corruption. If 
RCT determines that bad block replacement was partially completed when 
the disk went off line, RCT completes’ the bad block replacement 
process. If RCT determines that the write-back cache was not copied 
to the disk before the disk went off line, RCT software write-locks 
the disk so that the contents of the write-back cache are preserved. 
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5.3 INSTALLING RCT 


If you select a DU: device in SYSGEN, RCT... and DUDRV are both 
built. RCT... is installed and DUDRV is loaded in SYSVMR.CMD. You 
load or install and load RCT... and DUDRV only if: 


@ You have removed RCT... and/or unloaded DUDRV. 

@ You have edited SYSVMR.CMD to exclude one or both. 
If you manually install RCT... and load DUDRV, you must first install 
RCTs o56 Otherwise, you receive a message at the console terminal, 
indicating that the Replacement Control Task is not installed. 


To instali RCT, use the following command line: 


SING $ROT/TASKERCT. » » 


5.4 DISK CONFIGURATION OF MSCP DISKS 

Three address spaces on MSCP disks are relevant to RCT: 
@e Logical blocks (LBNs) 
@ Replacement blocks (RBNs) 


e Revector control tables 


5.4.1 Logical Blocks (LBNs) 


Logical blocks (LBNs) are accessible to user tasks for transferring 
data between the disk and the operating system. When the controller 
encounters a bad LBN and notifies DUDRV, DUDRV activates RCT to 
replace the LBN. 


5.4.2 Replacement Blocks (RBNs) 
Replacement blocks (RBNs) are blocks reserved throughout the disk that 


RCT allocates as substitutes for bad LBNs. RBNs cannot be directly 
accessed by user tasks during normal data transfers. 


5.4.3 Revector Control Tables 
The revector control tables are accessible only by RCT (by way of 
DUDRV) and the device controller. Each table entry corresponds to an 
RBN according to its location in the table. An entry contains the LBN 
being replaced and a code describing the status of the RBN. There are 
five status codes: 

@ ALLOCATED - The RBN is currently being used. 

e@e UNALLOCATED - The RBN is not being used. 


@ UNUSABLE - The RBN cannot be used. 
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e@ PRIMARY - The first RBN read when a bad block is replaced. 
e@ SECONDARY - The RBN read after the primary blocks are read. 


For a given LBN, a primary RBN is in a predetermined location, such as 
the last sector of the same track as the LBN. For that LBN, all other 
RBNs are secondary. 


Sector 0 of the revector control tables stores information in a _ flag 


word that enables RCT to determine if recovery techniques are required 
when a disk is brought on line. 


5.5 BAD BLOCK HANDLING ON MSCP DISKS 
Bad block handling on MSCP disks consists of four stages: 
@ Detection performed by the device controller, UDA5O 


@e Notification performed by the controller that notifies the 
driver, DUDRV 


e@ Replacement performed by RCT 


@e Revectoring performed dynamically by the device controller 


5.5.1 Bad Block Detection 


The UDA50O controller may detect a bad LBN while processing an I/O 
request from the driver. 


5.5.2 Bad Block Notification 

When the UDA50O controller detects a bad LBN, it notifies DUDRV by 
listing the bad LBN in an end packet. DUDRV stores this information 
in pool and activates RCT. 


DUDRV provides RCT with the information necessary to perform bad block 
replacement: 


e LBN 
e I/O packet address 


e Unit Control Block (UCB) address 


5.5.3 Bad Block Replacement 
RCT performs the following steps in bad block replacement: 


1. Emulates an ATTACH to the disk, inhibiting all I/O other than 
I/O necessary for bad block replacement. 


2. Reads the data from the bad LBN into a buffer in its data 
space. 
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3. Determines which RBN on the ' disk to use by applying a 
predetermined algorithm. 


4. Issues QIOs to DUDRV that update the revector control tables 
(discussed in Section 5.4.3). 


5. Updates the header and data of the bad LBN by issuing an 
IO.RPL to DUDRV. This 1/0 function code directs the 
controller to indicate in the header of the LBN that the LBN 
has been replaced either by a primary or secondary RBN and 
writes 128 copies of the address of the RBN in the data field 
of the LBN. 


6. Initializes the RBN by writing the data read from the _ LBN 
back to the bad LBN. Because the bad LBN has been replaced 
by the RBN, the data is written transparently to the RBN by 
the controller. 


If an RBN is bad, RCT treats it as a bad _ LBN. RCT finds 
another RBN, updates the revector control tables, marks the 
old RBN as unusable, and initializes the new RBN by writing 
the stored data back to the bad LBN. 


7. RCT detaches the unit, and normal I/O to the disk resumes. 


5.5.4 Bad Block Revectoring 


Revectoring is performed dynamically by the device controller. When 
the controller first accesses an LBN that has been replaced by RCT, 
the controller revectors (redirects) the I/0 to the RBN that’ RCT 
designated as the replacement for the LBN. Thereafter, I/O to the bad 
LBN is revectored transparently to the RBN without DUDRV activating 
RCT. 


5.5.4.1 Primary RBNs - When the controller detects a bad LBN whose 
header indicates that it has been replaced by a primary RBN, the 
controller directly accesses the RBN. 


5.5.4.2 Secondary RBNs - When the controller detects a bad LBN whose 
header indicates that it has been replaced by a secondary RBN, the 
controller must look up the address of the RBN before it can access 
the RBN. The controller finds the address of the secondary RBN in one 
of two ways: 


1. Checking the data field of the bad LBN, which contains’ the 
128 copies of the RBN 


2. Checking the revector control tables for the entry containing 
the bad LBN 


5.6 COMPLETING PARTIAL BAD BLOCK REPLACEMENTS 


When a disk unit is brought on line, RCT checks that no bad _ block 
replacement was in progress when the disk went off line by checking 
the flag word in sector 0O of the revector control table. If 
replacement needs to be completed, RCT completes the bad block 
replacement. 
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5.7 PREVENTING LOSS OF WRITE-BACK CACHE DATA 
RCT prevents loss of write-back cache data. 


A disk with the write-back-cache-in-use flag set will be write-locked 
each time it is brought on line. To write-enable such a disk, use the 
/WRITE qualifier with the MCR MOUNT command each time you mount’. the 
disk. RCT checks the write-back-cache-in-use flag word in sector 0 of 
the revector control tables, software write-locks the disk if the flag 
is set, and writes the following TKTN message to the console output 
device (CO:): 


ddnn: -- Write back caching data lost. Unit write locked 
where ddnn: is the disk that RCT has write locked. 
NOTE 


Because RSX-11M and RSX-11M-PLUS operating systems do 
not Support disks with write-back caching, this 
function is extremely rare. 


RCT performs this function only under the following circumstances: 


1. A disk with a write-back cache failed to copy the data from 
the write-back cache to the disk before going off line, while 
on another operating system (that supports write-back 
caching), and was then moved to an RSX-11M or RSX-11M-PLUS 
operating system. 


2. The revector control tables have been altered such that the 
write-back-cache-in-use flag is set. 


5.8 RCT AND OTHER RSX11M AND RSX-11M-PLUS UTILITIES 


Utilities such as BAD, BRU, and INI treat MSCP devices as 
non-last-track devices. RCT does not replace the BAD utility. You 
must run BAD on MSCP devices to create a bad block descriptor file 
before you initialize the disk. You can use BAD to find bad blocks 
and list them in a bad block descriptor file. However, the bad block 
descriptor file will not contain any information about blocks detected 
by the device controller and replaced by RCT. 


5.9 RCT AND THE ERROR LOGGER 


DUDRV notifies the Error Logger with an error log packet whenever an 
error has been detected that requires bad block replacement. RCT also 
generates an error log packet indicating that a bad LBN has_ been 
successfully (or unsuccessfully) replaced by an RBN. RCT logs the 
packet under the name of the task that issued the QIO resulting in the 
detection of the bad block by the controller. 


CHAPTER 6 


RESOURCE MONITORING DISPLAY (RMD) 


The Resource Monitoring Display .(RMD) is a privileged task that 
displays information about the resources in your. system. This 
information includes the active tasks, their location in memory, the 
amount of memory they occupy, and the available pool space. On video 
terminals such as VT52s, VT100-series, VT200-series, and Professional 
series terminals, RMD provides dynamic displays. On hardcopy 
terminals such as LA180s, RMD provides "snapshot" displays. RMD 
alters the display format according to terminal type without your 
having to set switches or rebuild the task. 


6.1 INTRODUCTION 
RMD consists of "pages". A page consists of 24 lines, which, on CRT 


terminals, is one screen. The program contains two kinds of pages: 
display pages and setup pages. 


6.1.1 Display Pages 


There are four display pages available on both RSX-11M and 
RSX-11M-PLUS systems: 


@ Memory (M) 

@e Active Task List (A) 
e Task Header (T) 

e Help (H) 


There are four additional display pages that are available only on 
RSX~11M-PLUS and ee evevene oi a 


: oe 1/0 Counts (1) 
i. “System Statistics (Ss) 
-@ Generar Statistics about a | Cache “Region (cy 
eo pekeiee Statistics about a Cached Device (D) 


You press the terminal keys indicated in parentheses to switch display 
pages. 
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6.1.2 Setup Pages 


There are five setup pages. Each setup page is associated with a 
display page. (The Help Display Page has no associated setup page.) 
You access a setup page from a display page by pressing the ESCAPE key 
on your terminal. The setup page documents and prompts you for setup 
commands, which alter the content of the information displayed on the 
associated display page. 


6.2 INSTALLING AND INVOKING RMD 


Individual users can invoke RMD at their terminals. For large systems 
that support many terminals, you may want to run RMD continuously ona 
slaved terminal near the computer. You use different procedures to 
install and invoke RMD for use by individual users and to run RMD ona 
slaved terminal. 


6.2.1 Using RMD at Individual Terminals 


On RSX-11M systems, RMD is available if you selected RMD at system 
generation. 


On RSX-11M-PLUS, RMD is always available. 


6.2.1.1 Installing RMD at Individual Terminals - You must install RMD 
in order for non-privileged users to use it. Privileged users can 
simply use the MCR RUN command to run $RMD. To install RMD, use_ the 
MCR INSTALL command at a privileged terminal: 


SINS $FMD 


6.2.1.2 Invoking RMD at Individual Terminals - From any terminal, you 
invoke an installed copy of RMD from MCR as follows: 


SEAT Cease dteseturcommands] . . 5 

where: 

page 
One of the display page abbreviations (M, A, T, or H). (There 
are also I, S, C, and D_ pages for RSX-11M-PLUS users.) The 
default page is the Memory Display (M). 


setupcommands 


A valid setup command for the display page that you have 


selected. The setup commands are the same as those available to 
you from the setup page associated with the display page you 
specified. The default setup commands are discussed in Sections 


6.4 through 6.6, which describe the content of each display page 
and how you use setup commands to alter display parameters. 


From a privileged terminal only, you can invoke an uninstalled copy of 
RMD using the MCR RUN command. However, MCR command line parsing is 
available only if RMD is installed. 
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6.2.2 Running RMD on a Slaved Terminal 


To run RMD on a slaved terminal and also allow users to invoke RMD at 
their own terminals, RMD must be installed twice using different task 
image files and different task names. 


On RSX-11M systems, if you selected RMD at system generation, you will 
find RMD.TSK (which has been task built at system ere due honk 
name ...RMD) in SYSUIC on your system disk. 


On RSX~11M-PLUS systems, you will find RMD.TSK (which has been task 
built at system generation with task name ...RMD) in SYSUIC on your 
system disk. 


RMD.TSK is the copy of RMD that the system installs for individual 
users to invoke. LUNs 1 and 2 in this task image have been assigned 
to TI: so that a user at any terminal can invoke RMD. 


To run RMD on a slaved terminal, do the following: 


1. From a privileged terminal, make a copy of RMD.TSK in SYSUIC 
on your system disk named RMDEMO.TSK. If your SYSUIC is 
[1,54] and your system disk is DRO:, use the following 
command sequence: 


SSET /TRF=€1954) 
"ASN THROT=SY3 
“PIP RMTEMO. TSK=RMO. TSK 


2. From a privileged terminal or from a command file to be executed 
at a privileged terminal, install RMDEMO using the following command 
sequence: 


~INS RMNEMO/TASK=RMTE MO 
PREA RANEMO 2 ttrnt 
“REA RMTEMO 2 btont 
SSEY /SLAVEet inn’ 

"RUA RTE MO 


where ttnn: is the terminal at which you want to run RMDEMO. 
This command sequence installs RMD with task name RMDEMO, 
reassigns LUNs 1 and 2 to the terminal you want to slave to 
the task, slaves the terminal, and invokes the task. 

Because the REASSIGN command alters the task image on disk, 


you must use two task images rather than simply installing 
RMD twice with different task names. 


6.3 THE HELP DISPLAY 


The Help Display documents how you switch display pages. You switch 
display pages by pressing a terminal key as follows: 
Key Explanation 
M Accesses the Memory Display 
A Accesses the Active Task Display 
r Accesses the Task Header Display 
I. Accesses the I/O Counts Display 
S Accesses the System Statistics Display 
Cc Accesses the General Statistics about a Cache Region 
D Accesses the Detailed Statistics about a Cached Device 
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The Help Display also documents how to exit from RMD and use _ the 
ESCAPE key to access setup pages from their associated display pages. 
{Because there is nothing to alter on the Help Display, no setup page 
is available from the Help Display.) 


The Memory, Active Task, and Task Header Displays use the entire 
screen. Therefore, you receive no prompts or documentation on display 
pages. To find out how to access a setup page from a display page or 
how to switch display pages, press the H key (for Help) to access the 
Help Display. 


6.4 THE MEMORY DISPLAY 


The Memory Display graphically represents the entire system memory, 
including the approximate size and locations of partitions and active 
tasks. The display also shows pool statistics, the name of the task 
that is currently executing, and other information about the status of 
your operating system. You access the Memory Display from another 
display page by pressing the M key (for Memory). To access the Memory 
Display from the MCR command line, you type the following: 


RMT M 

If you invoke RMD without specifying a display page: 
Pa rauen 

RMD defaults to the Memory Display. 


Figures 6-1 and 6-2 show "snapshots" of the Memory Display for RSX-11M 
and RSX-11M-PLUS respectively. The reverse numbers in each figure 
(white numbers in black circles) match the reverse numbers in the 
explanations that follow the two figures. Where a display field is 
the same for both RSX-11M and RSX-11M-PLUS, it is designated by the 
same reverse number in Figures 6-1 and 6-2. The matching explanation, 
however, appears only once. 
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Figure 6-1 RSX-11M Memory Display 
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Figure 6-2 RSX-lLIM-PLUS Memory Display 


Operating system type, version number, and base level. 


Six-character name that is a DECnet node name (if DECnet is 
running on your system) or the system name that you selected in 
SYSGEN (if DECnet is not running on your system). 


Size in K words of the system memory. 


For RSX-11M-PLUS systems, time elapsed in units of days, hours, 
and minutes, since the system was last bootstrapped. 


Current date and time. 


Name of the task that is currently executing or, if none is 
executing, *IDLE* (Executive executing the idle loop). 


Number of free blocks on the first four Files-1ll devices in your 
system. If a device is dismounted, RMD displays: "DMO". Ifa 
device is off line, RMD displays: "OFL". Magnetic tapes can 
also be displayed, but only if previously selected from the I 
setup page. 


Pool (dynamic storage region) information in the format: 


POOL=X: Y:Z 


where: 
X Number of words in the largest free block in pool 
Y Number of free words in pool 
Z Number of fragments in the pool free list 


The second line records the worst case of pool since you invoked 
RMD. This line is most useful if RMD has been running on a 
slaved terminal since the system was last booted. 
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On RSX-11M-PLUS systems, secondary pool information in the 
following format: : Ee © 


SECPOOL=A:B:C% 

where: 
A Number of free blocks in secondary pool 
B Total number of blocks in secondary pool 


ck Percentage of secondary pool that is free 
The second line records the worst case of secondary pool since 
you invoked RMD. This line is most useful if RMD has been 
running on a slaved terminal since the system was last 
bootstrapped. 
Partitions in the system using the following format: 
partitionname:type 
where: 
type 
For RSX-11M systems (Figure 6- A), one of the following: 
: Task partition : 
Subpartition _ 


System-controlled (aynamic) partition 
Common partition 


aAvuaH 


For RSX=-11M-PLUS systems (Figure 6-2), one of the following: 


D System-controlled (dynamic) partition 
P Secondary pool partition 


Number of tasks in memory and amount of memory they use, and 
number of active tasks swapped or checkpointed out of memory and 
the amount of memory they would require. 


Name of each task, common, or driver in memory and its location 
in memory using the following symbols to designate size, type 
(task, common, or driver), and other attributes: 


Symbol Attribute 

< > Active task 

E ] Task not active, yet occupies memory 

! | Named common 

+ + Unnamed common (displayed name is first attached 
task) 

( ) Loaded driver using device mnemonic 


----- Task not fixed in memory 
=== Task fixed in memory 


The hyphens and equal signs represent the approximate amount of 
memory that each task, driver, or common occupies. Where the 
display shows only one delimiter and no hyphens or equal signs, 
the open delimiter is in the same location as the closing 
delimiter of the preceding task. 


RESOURCE MONITORING DISPLAY (RMD) 


@ Partition size and location. The beginning of each partition is 
marked with the same symbols as those listed previously plus the 
following additions for both operating systems: 


E Executive 
P Pool 


The lines of asterisks are approximate representations of the 
amount of memory occupied by each partition. The numbers are in 
1K word increments. Each numerical character also represents the 
same amount of memory as an asterisk. RMD always divides the 
system memory into groups of eight units. 


14) System error count sequence recorded by the Error Logger (always 
zero if Error Logger not present in your system). 


6.4.1 Altering the Memory Display from the Setup Page 


To alter the Memory Display, you press the ESCAPE key, which accesses 
the setup page for the Memory Display. The setup page documents and 
prompts you for commands which you use to alter the Memory Display. 
You can enter multiple commands after each prompt by using commas as 
separators. The setup commands available for altering the Memory 
Display are as follows: 


@e FREEx=ddnn:, where x is a number from O to 3 and ddnn: is a 
device name and number 


@e RATE=s, where s is the replot rate in seconds 


You can truncate these commands to their shortest unique forms. These 
setup parameters stay in effect until you alter them, even if you 
switch to another display page and back to the Memory Display. 


6.4.1.1 The FREE Command - You use this command to determine the four 
Files-ll devices for which you want the Memory Display to show the 
available free blocks. This information is (7) in both Figures 6-1 
and 6-2. The default is your system disk (SY:) and the next three 
Files~-1l devices in your configuration. 


6.4.1.2 The RATE Command - You use this command to determine how 
often RMD replots the Memory Display if you are running RMD on a CRT. 
The default replot rate is once per second. 


6.4.2 Altering the Memory Display from the MCR Command Line 


You can enter the FREE and RATE commands as part of the MCR command 
line. (The general format of the MCR command line is discussed in 
Section 6.2.1.2.) For example, when you enter the MCR command line 


“RMI Myo FREE S@0M6% RATE =3 
RMD displays the number of free blocks on DMO: instead of the fourth 


Files-l1l1 device in your configuration and replots the display every 3 
seconds instead of every second. 
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To change the second and third Files-ll devices to DB1: and DB2: 
respectively, use the following MCR command line: 


SRMT My FREELSUBL? »sFREE2=2B2$ 


These setup parameters stay in effect until you alter them by using 
setup commands from the setup page. Even if you switch to another 
display page and back to the Memory Display, RMD does not restore the 
default setup parameters. 


Other display pages allow you to select devices as well. These 
devices are common across all pages. Therefore, if you select F1=DMO: 
for the M page, and then switch to the I page, DMO: will be the first 
displayed device, not SY: (which would be the default). 


6.5 THE ACTIVE TASK DISPLAY 


The Active Task Display shows you the active tasks in the system. You 
access this display from another display page by pressing the A key 
(for Active Task). To access this display from the MCR command line, 
you type the following: 


SRM A 
This display has six fields: 
1. Name of the task 
2. Length of the task in octal bytes 
3. Terminal that issued the task 
4. Running priority of the task 
5. Outstanding I/O count 
6. Status flags 


The status flags use the same mnemonics as the MCR ATL command. See 
the RSX-11M/M-PLUS MCR Operations Manual for the definitions of the 
status flags. 


6.5.1 Altering the Active Task Display from the Setup Page 


To alter the Active Task Display, you press the ESCAPE key, which 
displays the setup page for the Active Task Display. The setup page 
documents and prompts you for commands that you use to alter the 
Active Task Display. You can enter multiple commands after each 
prompt by using commas as separators. The setup commands) available 
for altering the Active Task Display are as follows: 


@e OWNER=ttnn: - Where ttnn: is the terminal that issued the 
task. 


The OWNER command allows RMD to display only those tasks that 
have been issued by a particular terminal. The default is 
ALL, which displays tasks issued from all terminals. 
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@e PRIORITY=p - Where p is a task's running priority. 


The active task list may be too long to fit on one screen. 
You use the PRIORITY command to determine the highest priority 
tasks that you want to see. The default is 250, the highest 
possible priority. 


@e RATE=s where s is the replot rate in seconds. 


The RATE command allows you to determine how often RMD replots 
the Active Task Display, if you are running RMD on a CRT. The 
default replot rate is once per second. 


e TASK=taskname - Where taskname is the name of the task whose 
header you want to display. 


The TASK command allows you to look at a specific task header. 
This command is an exception because it is the only setup 
command that switches display pages. There is no default for 
the TASK command. The Task Header Display is discussed in 
Section 6.6. 


You can truncate these commands to their shortest unique forms. These 


setup parameters stay in effect until you alter them, even if you 
switch to another display page and back to the Active Task Display. 


6.5.2 Altering the Active Task Display from the MCR Command Line 

You can enter the same setup commands discussed in the previous 
section as part of the MCR command line. For example, when you enter 
the MCR command line: 


SEMT Go PRIORI TY=200 RATE =3 


RMD displays the Active Task Display using 200 as the maximum task 
priority and replots the display every 3 seconds. 


To display only those tasks issued by your terminal, type the 
following: 


SRD As TNE Re Tt 


6.6 THE TASK HEADER DISPLAY 


The Task Header Display shows you the task header of the task you 
specify. You access this display from another display page by 
pressing the T key (for Task Header). If no task is currently 
specified, RMD shows you the setup page first so that you can specify 
the task whose task header you want RMD to display. 


To access the Task Header Display from the MCR command line, you type 
the following: 


PMO Ts TASK=taskname 


where taskname is the name of the task whose header you want RMD to 
display. 
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If you invoke RMD from the MCR command line without specifying the 
name of a task: 
SRMO T 


RMD displays the setup page first so that you can specify the name of 
the task whose header you want RMD to display. 


The Task Header Display shows you the following information about the 
specified task: 


@ Name of the task 
@ Name of the partition in which the task runs 


e Status flags, which have the same mnemonics as in the Active 
Task display 


@ Owner of the task by terminal number 
@® Outstanding I/O count 

e Default priority 

e Running priority 

@ Swapping priority 

e Length in decimal words 


e Contents of the six general purpose registers, the program 
counter, and the Processor Status Word 


e Contents of the Directive Status Word ($DSW) 
e Local event flags 
e Logical unit number (LUN) assignments to a maximum of 26 LUNs 


When RMD displays file names in the list of LUN assignments, the file 
name is the name of the file when it was created. If the file has 
been renamed, the RMD display will not reflect the current file name. 


6.6.1 Altering the Task Header Display from the Setup Page 


To alter the Task Header Display, you press the ESCAPE key, which 
displays the setup page for the Task Header Display. The setup page 
documents and prompts you for commands that alter the Task Header 
Display. You can enter multiple commands after each prompt by using 
commas as separators. The setup commands available for altering the 
Task Header Display are as follows: 


@e RATE=s - Where s is the replot rate in seconds. 
The RATE command allows you to determine how often RMD replots 
the Task Header Display if you are running RMD on a CRT. The 


default replot rate is once per second. 


e TASK=taskname - Where taskname is the name of the task whose 
header you want to display. 
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The TASK command changes the task header to be displayed. 
There is no default. The TASK command has the same function 
as the TASK command on the Active Task Display, except that 
here it does not switch display pages. 


You can truncate these commands to their shortest unique forms. These 


setup parameters remain in effect until you alter them, even if you 
switch to another display page and back to the Task Header Display. 


6.6.2 Altering the Task Header Display from the MCR Command Line 


Both the RATE and TASK commands are available to you from the MCR 
command line. If you invoke RMD using the following command line: 


SRM TeRATEs2+TASK=...ENT 
RMD displays the Task Header Display for EDT, replotting the page 
every 2 seconds. You must give the full task name. In this case the 
taskname is "...EDT", not "EDT". 
If you do not specify a task name in the MCR command line: 

SAMO Tr RATES 2 
RMD first displays the setup page so that you can select a task whose 


header you want RMD to display. The replot rate will be set to 2 
seconds. 


6.7 DISPLAYS AVAILABLE ONLY oN RSX-11M-PLUS 


Four displays are available only on - RSX-11M-PLUS systems: the 1/0 
Counts Display, the System Statistics Display, the General Statistics 
about a Cache Region Display, and the Detailed Statistics for a Cached 
Device Display. These displays are invoked by the commands RMD I, RMD 
S, RMD C and RMD D, POSPSGtLvely: 


6.7.1 The I/O Counts Display _ 
The 1/0 Counts display shows you I/O and error logging counts for up 
to six error logging devices. By default, the first six error logging 
disk devices in your hardware configuration are displayed. You access 
this display from another display by pressing the I key (for I/0). To 
access this display from the MCR command line, you type the following: 
“RME I , 

The I/O Counts Display has 10 fields for each device: 

1. Device name of the displayed device 

2. Total number of I/O requests to the device 


3. Number of 1/0 requests issued to the device in the last 
second 


4. Average number of I/O requests issued to the device per 
second : 
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5. Average number of ey 
the last second — 


gr ier a 1/O request during 


6. Average number ee: crossed per 1/O request 
7. Number of words ‘transferred during the last second 
8. Average ‘number of words transferred per second 
9. Count and Limit of soft 1/o errors 

210.) Count and limit of hard I/O errors 


The 1/0 Counts display works only on video terminals. 


6.7. 1. 1 Altering the re Counts | Display - from the Setup Page ee To 
alter the I/O Counts Display, you press the ESCAPE key, which displays 
the setup page for the 1/0 Counts Display. The setup page lists the 
available commands you can use to alter the I/O Counts Display, and 
prompts you for a command. You can enter multiple commands after each 
prompt by using commas as separators. The setup commands available 
for altering the ‘1/0 Counts Display are as follows: 


e DEVICEx=ddnn: - Where x is a number from 0 to 6 and ddnn: is 
an error fogging: devi , Le 2S 


oo detect which error Losakns 
The device specified must be an 
lect magnetic tape devices 
i tape devices, fields 5 and 
e- the DEVICE ‘command to 
rst six error logging disk 
ration are displayed by 
oo boga+ng Manual for a 


The DEVICE ‘command. al 
devices are to be d 
error logging device. 
from the setup page. 
6 are suppressed. If 
epecify a device or 
devices in. your — 
default. See the 
list of the error 


° (RATERS ~ Where 5 Ss is in seconds. 
The RATE command allo 
the I/0 Counts Di 
Giephey terminal. T 


rmine how often RMD replots 
-are running RMD on a video 
efault rep ot rate is once per second. 


You can trancate these commands to their shortest unique shia. These 
setup. parameters — stay in effect until you alter them, even if you 
switch fo another aiely ‘Peay and then return to the ‘1/07 Counts 
eran | we 8 


6.4, Ll. 2 Agari the 1/0 Counts ieee from the MCR Command Line - 
You can enter the DEVICE and RATE commands as part of the MCR command 
line. For example, when you enter the following command line, RMD 
displays 1/0 bcteecsd information for DB3: and replots the display every 
2 seconds: re ee 


RMT! T DEVICE2= “DRS ty RATES 


The ieoraneion for DR3: is. displayed in the position ‘that would 
normally display | information for the third error logging device in 
your hardware configuration. 
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19. Average number of running CPU ticks per second 

20. Total number of zero CPU intervals 

21. Number of zero CPU intervals during the last second 
22. Average number of zero CPU intervals per second 

23. Total number of task checkpoints 

24. Number of task checkpoints during the last second 


25. Average number of task checkpoints per second 


6.7.2.1 Altering the System Statistics Display from the Setup Page - 
You can alter the replot rate on the System Statistics Display by 
pressing the ESCAPE key, which displays the setup page for the System 
Statistics Display. The setup page lists the command format for 
altering the replot rate, and prompts you for a command. The command 
for altering the replot rate of the System Statistics Display is as 
follows: 


RATE=s, Where s is the replot rate in seconds. 


You can truncate this command to the single letter R. This setup 
parameter stays in effect until you alter it, even if you switch to 
another display page and then return to the System Statistics Display. 


The default replot rate is once per second. 


6.7.2.2 Altering the System Statistics Display from the MCR Command 
Line - You can enter the RATE command as part of the MCR 

command line. For example, when you enter the following MCR command 

line, RMD replots the System Statistics Display once every 2 seconds: 


RMD S»sRATE=2 


This setup parameter stays in effect until you alter it by using the 
RATE=s command from the setup page. Even if you switch to another 
display page and then return to the System Statistics Display, RMD 
does not restore the default replot rate. 


6.7.3 The General Statistics About a Cache Region Display 


The General Statistics about a Cache Region display (RMD C display) 
shows you general statistics about a particular cache region. 
(However, you must have previously established disk data caching 
through the MOUNT or SET command to use this display. For more 
information on disk data caching, see Chapter 19 of this manual.) You 
access this display from another display by pressing the C key (for 
Cache Region). To access this display from the MCR command line, you 
type the following: 


RMD C 
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The RMD C Display has 14 fields for each region: 
1. Name of the cache region. 


2. Region size in octal of the cache region in 32 word memory 
blocks, followed in parentheses by the decimal number of disk 
blocks available in the cache extent area. 


3. Device name. 


4. Total count of all reads issued to that device. These 
include VIRTUAL, READAHEAD, DIRECTORY, LOGICAL, and OVERLAY 
read requests. 


5. Read hit rate (percentage of all read requests that were 
satisfied by the cache). 


6. + Read fail rate (percentage of all read requests that could 
not be satisfied by the cache). 


7. Read load rate (percentage of all read requests that resulted 
in data being loaded into the cache) for the cache region. 


8. Total writes (count of all write requests issued to the 
device, including VIRTUAL, DIRECTORY, and LOGICAL writes). 


9. Write hit rate (percentage of all write requests that caused 
updating of blocks already loaded» in the cache). 


10. Write fail rate (percentage of all write requests that could 
* not be directed to the cache because of an extent overlap). 


ll. Write defer rate (percentage « of all write requests that were 
deferred). Le 


12. Total 1/0 operations. (total of all read and write operations 
: for the device. 


13. Cache Used (percentage of cache extent storage area used by 
the device). 


14. Totals for the cache bo 


6.7.3.1 Altering the RMD C Display from the Setup Page - To alter the 
Display, you press the ESCAPE key, which displays the setup page for 
the General Statistics about a Cached Region Display. The setup page 
lists the available commands you can use to alter the Display, and 
prompts you for a command. You can enter multiple commands after each 
prompt by using commas as separators. The setup commands available 
oor metering this display are: 


@ REGION=name specifies the region to be displayed. 


This command allows you to select the cache region to be 
displayed. The default region is CACHE. 


@ RATE=s, Where s is the refresh rate in seconds. 


This command allows you to determine how often RMD replots the 
General Statistics about a Cache Region Display, if you are 
running RMD on a video display terminal. The default refresh 
rate is once per second. 
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You can truncate these commands to their shortest unique forms. (For 
this display page, the shortest unique form is RA for RATE, and RE for 
REGION.) These setup parameters stay in effect until you alter them, 
even if you switch to another display page and then return to the RMD 
C Display. 


6.7.3.2 Altering the RMD C Display from the MCR Command Line —- You 
can enter the REGION and RATE commands as part of the MCR command 
line. For example, when you enter the following command line, RMD 
displays general statistics for the region named CACHE and replots the 
display every 2 seconds: 


.RAT Ce REGTON=CACHE sRATE#2 


The information displayed is for the region named CACHE and is 
refreshed every two seconds. 


These setup parameters stay in effect until you alter them by using 
setup commands from the setup page. Even if you switch to another 
display page, and then return to the RMD C Display, RMD does not 
restore the default parameters. 


6.7.4 The Detailed Statistics About a Cache Region Display 


The Detailed Statistics about a Cache Region display (RMD D display) 
shows you detailed statistics about a particular cache region. 
(However, you must have previously established disk data caching 
through the MOUNT or SET command to use this display. For more 
information on disk data caching, see Chapter 19 of this manual.) You 
access this display from another display by pressing the D key (for 
Detailed Statistics.) To access this display from the MCR command 
line, you type the following: . 


’RAD 
The RMD D Display has 15 fields for each cached device: 
1. Region Name 
2. Region Size (in octal, measured in 32 word memory blocks.) 


3. Cache Status field (whether the cache is ACTIVE and/or 
ENABLED ) . ACTIVE means the device is being cached through 
the region; ENABLED means that the device will automatically 
be cached when it is mounted (even if the MOUNT command does 
not explicitly request that the device be cached). 


4. Requests Being Cached field (types of cache I/O operations 
enabled for the device). The types can be VIRTUAL (VIR), 
READAHEAD (RDH), DIRECTORY (DIR), LOGICAL (LOG), and OVERLAY 
(OVR). 


5. Reads section (number of read requests issued for each of the 
I/O types listed in the display, as well as the total of all 
read requests). 


6. Read Hit Rate, Read Load Rate, Read Overlap Rate, and the 
Extent Too Big rate for each type of request. Each of these 
rates is computed as a percentage of the total number of read 
operations for the particular type of request. 


RESOURCE MONITORING DISPLAY (RMD) 


: ‘7. Maximum Extent Size f 


se xe ete yenued for 
1 of all write requests. 
oe do not | Seong 


8. Writes section sh 
each of the 1/0 
Note that READAHE 
80. ehese fields a 


9. Write. Hit Rate nnd eedee Souciap Rate. for each ee (ae “Ao 
request. Each of these rates is computed as a percentage of 
the total number of write Eero of a particuier aa 


gota amount of each | type of 1/0 as well as the t 
of all ae a 


ey Le type. All. ganhe 1/0 racuuees require that an 1/0 
packet be allocated from primary Laas a 


a petey ‘Bool Allecation Failure Rate 
allocation cannot be done) as a “percentage | of the total 
number of 1/Cs issued for that device. oe 


13. Cache Pool Allocation ‘Failure. ‘Rate. is ‘gimiiee: to. the ‘failure 
oe rate for peimery po _ alloca: on xcept that allocation from 

ead operations. The rate 
ge Of slat total number of 


is | therefore pane 
read RST CT ONS 5. 


14. Read Load Pallare Rate 


peeae! of all ache load 
apie eet tek fet ie 2 


/o ge 


wets operations were 
ed as a percentage of the 


15. Deferred Write Rat 
able to be deferre 
total number of w 


6.7.4.1 Altering the RMD D 
Display, you press the ESCA 
the Detailed Statistics Abo 
lists the available c 
prompts you for a command. 


, setup. baae - To alter. the 


for altering this display aren 


o DEVICE1=ddnn: ~ specifies the devices to be “aleplayed. 
This command slices you to select the device to be: @leplaved. 
_. The default device is SY:. Note that you can: only display one 
_ device. po ee 


| w Raess, Where Ss is the refresh rate in seconds. De 


This command allows you to determine how often RMD  replots ue 
Detailed» Statistics about a Cache Region Display, if you are 
_ - Funning RMD on a video display terminal. The daha reece refresh 
eee is once per BECONG 


You can truncate these comands to their shortest onigue forms. ke 
setup parameters stay in effect until you alter them, even if you 
switch to another display page and then return to the RMD D Display. 
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6.7.4.2 Altering the RMD D Display from the MCR Command Line - You 
can enter the DEVICE and RATE commands as part of the MCR command 
line. For example, when you enter the following command line, RMD 
displays detailed statistics for DR3: and replots the display every 2 
seconds: 
VRMED Te TEVICKELEaNRSt RATE =2 

The information for DR3: is displayed. 

These setup parameters stay in effect until you alter them by using 
setup commands from the setup page. Even if you switch to another 


display page, and then return to this display, RMD does not restore 
the default parameters. 


6.8 MODIFYING THE TASK-BUILD COMMAND FILE 


You can modify the task-build command file to change the defaults for 
RMD. 


On RSX-11M systems, this file is LB:[{1,24]RMDBLD.CMD for mapped 
systems and LB:[1,20]RMDBLD.CMD for unmapped systems. 


On RSX-11M-PLUS systems, this file is LB:[1,24]RMDBLD.CMD. 


6.9 ERROR MESSAGES 


RMD generates the following error messages: 


RMD - Allocated screen buffer too small for this device 


Explanation: RMD requires more internal memory to display the 
requested display on the type of terminal on which you are 
running RMD. 


User Action: Rebuild RMD with a larger screen buffer by 
modifying the task-build command file as discussed in Section 
6.8. 


RMD - Illegal command - xxxxx 


Explanation: You entered an illegal command xxxxx either on the 
MCR command line or in response to the COMMAND> prompt on a setup 


page. 
User Action: Enter the correct command as documented in this 
chapter. 

RMD - Page does not exist 


Explanation: You requested a display page from the MCR command 
line that does not exist. 


User Action: Enter the command line again specifying a correct 
display mnemonic. 
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RMD - Segment ‘'xxxxxx' not found 


Explanation: The module xxxxxx was not found in the task image 
for RMD. This denotes an error in how RMD was task built. 


User Action: Check that RMD has been built with all the required 
modules. 


RMD - Terminal type not defined 


Explanation: The operating system and RMD do not recognize your 
terminal type. 


User Action: Check your terminal type using the MCR- command 
SET /TERM=TI:. If this setting is incorrect, use the MCR SET 
command to correct your terminal type setting. If the setting is 
correct, move to a different type of terminal. 


RMD - Terminal type not set 


Explanation: You did not build RMD to display the requested 
display page on the type of terminal to which your terminal is 
set. 


User Action: Determine your terminal type setting using the 
MCR SET /TERM=TI: command. If this setting is incorrect, use 
the MCR SET command to correct your terminal type setting. If 
the setting is correct, move to a different type of terminal. 


RMD - Terminal type not yet supported 
Explanation: RMD does not recognize your terminal type. 


User Action: Determine your terminal type setting using the 
MCR SET /TERM=TI: command. If this setting is incorrect, use 
the MCR SET command to correct your terminal type setting. If 
the terminal type is correct, you can write a terminal 
characteristics module for the terminal similar to the one in 
[14,10]JV52CHA.MAC. Then, assemble the module, include the new 
module in the ODL file and rebuild RMD. 


CHAPTER °7 


SETTING UP AND RUNNING THE QUEUE MANAGER 


This chapter is directed to the system manager or operator who will be 
setting up and running the Queue Manager and batch processors on an 
RSX-11M or RSX-11M-PLUS system. Except where noted, all commands’ in 
this chapter are privileged. 


Most RSX-11M/M-PLUS systems will include the Queue Manager for the 
convenience of multistream line PREECE spooling. 


‘The Queue Manager on. RSX-11M-PLUS. also supports transparent spooling 
and batch processing. You can have the Queue Manager without batch 
processing, but a“ cannot have: batch Prccees tag without the Queue 
uc oe ee oe oe ee. _ 


In UFD [1,2] on the eye ten disk (LB:), you will find the file 
STARTUP.CMD. This file includes commands for setting up the Queue 
Manager on a standard configuration. This sets up the QMG_ subsystem 
on a baseline system with one print processor, (and, on RSX-11M-PLUS 
systems, one batch processor.) The information in the present chapter 
will help you alter STARTUP.CMD to set up a Queue Manager tailored to 
your installation. 


This chapter consists of a narrative introduction and review of the 
process of setting up the Queue Manager {and batch processors} and 
detailed descriptions of all commands to the Queue Manager. 


The queue management subsystem consists of three major components on 
RSX-11M.  (RSX-11M-PLUS systems have a fourth major component.) The 
components are as follows: 


1. A command line interpreter (QMGCLI) that processes both print 
requests and queue access commands as described in the 


RSX-11M/M-PLUS Batch and Queue Operations Manual. QMGCLI 
communicates with the Queue Manager by sending data packets 
to it. 


2. The Queue Manager (QMG) that controls the queueing and 
dequeueing of print jobs. QMG communicates with QMGCLI and 
the despooler tasks to process print jobs. 
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On RSX-11M-PLUS systems only, QMG also controls batch 
processing. The RSX-11M-PLUS QMGCLI accepts batch requests 
as well as print requests. The RSX-11M-PLUS QMG controls the 
queueing and dequeueing of batch jobs. The RSX-11M-PLUS QMG 
also includes a batch processor prototype task, BPR. This 
task creates a virtual terminal that passes commands to the 
batch processor and to a system CLI, either MCR or DCL, or a 
user-written CLI. (Note that QMGCLI is not a CLI in this 
sense.) The BPR task can be installed as many as 16 times 
with task names in the form BAPnnn, where nnn represents one 
to three Radix-50 characters. 


3. The despool prototype task (LPP) that attaches a device and 
despools print jobs to it. An LPP must be installed for each 
device to be used as a spool device with the task name ddn, 
where dd is the generic device name and n is the unit number. 
A despool device is a device under the control of QMG. 


4. On RSX-1LIM-PLUS only, the source files in SyY0:[121,10] make 
up the print processor task. You can use this as a model if 
you wish to write output despoolers for your applications. 


7.1 INTRODUCTION AND REVIEW 


The following narrative explains how to bring QMG into your’ system. 
Both MCR and DCL commands are included. 


This can be done interactively, but in most cases you will include it 
in an indirect command file invoked as part of the system's STARTUP 
procedures. 


NOTE 


On RSX-11M-PLUS systems with DCL as a CLI, the DCL 
form of these commands can be used on both MCR and DCL 
terminals. This is for compatibility with 
RSX-LIM-PLUS Version 1.0. 


Each of the following steps includes a block diagram of the Queue 
Manager, processors, and devices as they exist at that point in the 
procedure. Those parts of the subsystem brought into being by that 
step are shown in red. 
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l. Install the Queue Manager. It will be found with the 
privileged utility tasks. 


DCL OINSTALL /CHECKFOINT $QMG 


MCR> INSTALL $QMG/CKP=YES 


QUEUE 
MANAGER 
stopped LPO: 
unspooled 
PRINTS 
PRINT 
FCS 
Cc > 
> SUBMIT > PRINT 


ZK-154-81 
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2. Start QMG. The command starts the Queue Manager and 
initializes the default queues PRINT and BATCH. It creates 
the queue file on LBO: if the file is not there. The 
command also clears all assignments previously recorded. If 
the queue file was intact, all queues will still contain 
their jobs, but the jobs are not assigned to processors. 
(Processors will have to be reinitialized, but queues will 
not.) 


QNCLOSTART/QUFUE /MANAGER 


MCRSQUE /STALTOMG 


QUEUE 
MANAGER 


LPO: 
unspooled 


PRINT$ 
PRINT 


FCS 


> SUBMIT 


ZK-155-81 


T 
pb 
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3. The default print queue PRINT was initialized in the previous 
step, but you must initialize at least one more queue named 
for each line printer. This queue will serve the many system 
tasks that conventionally send output to LP: by directing 
this output to QMG. This is known as a device-specific 
queue. PRINT is a general queue. 


A device-specific queue must be initialized before the 
associated device is initialized (spooled). For LPO:, the 
device-specific queue is named LPO. 


UCLSINITIALIZE/QUEUE LPO/SPRINT 


MOROQUE LPOSvE RSF 


QUEUE 
MANAGER 


LPO: 
unspooled 


PRINT$ 
PRINT 


> PRINT 


> sumer 


ZK-156-81 


Initialization names, creates, and starts a queue. 


You will need this extra queue even if your system has. only 
one printing device. You can initialize as many as 14 
additional print queues for a total of 16. One must be the 
default queue PRINT. The remaining 15 can be device-specific 
or general queues. There must be a device-~specific queue for 
every spooled (initialized) output device. Queues for 
application processors are print queues. 


7-5 


SETTING UP AND RUNNING THE QUEUE MANAGER 


4. Next, you must install a print processor for each physical 
printing device that will be set spooled (by means of 
INITIALIZE). This processor "owns" the printer; the 
processor name must’ be derived from the printer name. For 
example, LPO: is owned by LPO. LPP.TSK installs 
automatically as _ LPO. The print processors will be found 
with the privileged utility tasks. 


QCLSINSTALL $1 FP 


MCR TNS $LPP 


QUEUE 


MANAGER LPO 


LPO: 
unspooled 


PRINTS 
-PRINT 


> SUBMIT > PRINT 


ZK-157-81 


If you have additional output devices, use the  /TASK 
qualifier to install their print processors under the proper 
names. You can initialize as many as 15 print processors. 
Applications processors are considered print processors for 
this count. 


DOLE INSTALL /TASK IL RT €l PF 


MCRSTNS $LPP/STASKELP YL 
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5. You must initialize your print processors, setting whatever 
attributes you wish. Any initialization of a print processor 
sets the associated output device spooled. 


QCLSINITIALIZE/FRINTER LRO/FLAG_ PAGE? 2/FORM3 0/1 OWERCASE 


MCRSQUE LFOS/SP/FLE2/F030/1L0W 


QUEUE 
MANAGER 


PRINTS 
-PRINT 


> PRINT 


ZK-158-81 


The command assigns the queue LPO to despooler LPO. The 
queue must exist before you initialize the processor LPO. 
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6. Next, you must install the interface 


Manager and other system tasks. This interface is handled by 
SQMGPRT.TSK. It must be installed as PRT.... 


It will be 
found with the nonprivileged utility tasks. 


between the Queue 


DCLSINSTALL/TASRIFRT... $QMGFRT 


MCORS INS $QMGFRT/TASK=FRT.« + 


> 
QUEUE | 


PRINTS 
ERT: PRINT 


> SUBMIT > PRINT 


ZK- 159-81 
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7. Next, you must assign queues to print processors. Assignment 
establishes the path between queue and print processor. The 
Queue Manager can send jobs only to assigned processors. 


QRCLSASSIGN/QUFUE FRINT LEO 


MORSQUE LPOSZASSERINT 


pacled 


PRINTS 
-PRINT 


> SUBMIT > PRINT 


ZK-160-81 


When you complete this step, two queues are now assigned to 
the same processor (because queue LPO was assigned to 
processor LPO at initialization). 


You can assign a queue to more than one processor and you can 
assign more than one queue to a processor. 


If you initialize a queue, but do not assign it, jobs sent to 
that queue will not be processed until the queve is assigned. 


This completes the installation process for the RSX-11M OMG. 
The remaining steps apply to RSX-l1M-PLUS only. 
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8. You must now 


This task will be 


| DCL >INSI 


> susmit ! 
2 2K181-81 


You can insta 


. ; cessors. They must 
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10. The default queue _ i was initialized by 

START/QUEUE/MANAGER, but you may initialize as many as 15 
additional batch queues with names of as many as. six 
alphanumeric characters in any form. | 


CL>INI/Q POGO/RATCH 


MCRD QUE POGOI/CRIB 


— 
QUEUE | 
BAND MANAGER vie a 


LPO: 
spooled 


PRINT 


ne PRINTS 


> suBMIT ae > PRINT 
OP TN ge eae 2K-169-81 
Note that batch processors do not need device-specific queues 
because no devices are associated with them. 
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os 2 169-81 | 

eee ait to a 
"O Cy il decir be segues 

until the qi oe 
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7.2 QUEUE MANAGER COMMAND DESCRIPTIONS 


The operations of QMG are controlled through a number of DCL and MCR 
commands. The functions invoked are identical, but the command syntax 
is different. Use whichever command syntax you are accustomed to. In 
this manual, both forms of the syntax appear in the command 
descriptions; the DCL commands and command elements are to the left 
and the MCR to the right. In the section titles, MCR commands or 
command elements appear in parentheses. In the examples, commands are 
identified explicitly by the DCL> and MCR> prompts. 


The processors, devices, and device-specific queues all have names 
derived from the name of the spooled device. Thus, if LPl: is the 
spooled device, the processor that “owns" it is called LPl and _ the 
device-specific queue is also called LPl. The colon (:) portion of 
the device name can be omitted from references in DCL commands’ to 
processors, devices, and queues. The colon portion must be included 
in references in MCR commands to processors, devices, and queues. You 
can include the colon portion in any DCL command, but it is required 
only in MCR commands. Furthermore, in MCR commands, all queue names 
must be terminated by a colon, whether they are derived from device 
names or not. Thus, if you wish to refer to a queue named XPRESS in 
an MCR command, you must refer to that queue as XPRESS:. 


The general format of DCL QMG commands is as follows: 
DCL>DCLcommand/QMGqualifier[s] parameter[s][{/qualifier[s]] 

The general format of MCR QMG commands is as follows: 
MCR>QUE ddnn: /function[:option[{s]][/swis]] 

Command descriptions are given in the order they are used in the 


narrative, except that any counteracting commands are described just 
after the setup commands they counteract. 


7.2.1 INITIALIZE/ (QUE /CR/SP) 
These commands create, name, and start a queue or processor. 
When you initialize an output processor, you are setting its 


corresponding device spooled. A spooled device can be accessed by the 
Queue Manager. The processor or task must be installed. 


7.2.1.1 INITIALIZE/QUEUE (QUE /CR) - INITIALIZE/QUEUE creates, names, 
and starts a queue. 


Formats 
DCL> INITIALIZE/QUEUE queuename/qualifier 
DCL Parameter Qualifiers 


/ BATCH 
/PRINT 


MCR>QUE ddnn:/CR:typ 
MCR Queue Types 


PRINT 
BATCH 
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Parameter 
queuename 
This specifies the name of the queue to be initialized. 


Queue names BATCH and PRINT are reserved, because the BATCH and 
PRINT queues are initialized by the START/QUEUE/MANAGER (QUE 
/STA:QMG) command. 


The queue named BATCH is initialized on RSX-11M Bystene: but is 
not used, and is not accessible or displayed. 


You must initialize a queue for every output device to which the 
Queue Manager is to send print jobs. These are called 
device-specific queues. . Otherwise, any six alphanumeric 
characters make an acceptable queue name for a general queue. If 
you have no processor LPl, LPl is then a general queue name. 


Device-specific queues must be initialized before the associated 
processor. 


Parameter Qualifiers 


This qualifier can be either /BATCH or /PRINT. The qualifier 
tells the Queue Manager what kind of queue is being initialized. 
Queues for applications processors are print queues. 


The default qualifier is /PRINT. For the sake of clarity, you 
should always include the qualifier when initializing a queue. 


Examples 


TCL =ASSIGN/QUEUE XPRESS LPO? 
MCRSQUE LPO? /ASS XPRESS 


This example creates, names, and starts a print queue named 
XPRESS. The queue can now accept print jobs, but it must be 
assigned to an output processor before jobs can be taken from the 
queue. 


QCLSINTTIALTZ7E/QUEUE XPRESS/PRINT 


MORSQUE XPRESS? /CRSPRINT 


This command assigns the queue initialized in the previous 
example to a print processor. 


QCLSINITIALIZE/QUEUE LFO/FRINT 
NCL UNTITIALIZE/PRINTER LFOS 


MCRSQUE LFOS/SCR 
MCORGQUE LPO? /SP 


This example creates, names, and starts a print queue named LPO. 
This is a device-specific queue whose name is derived from the 
name of an output device. This queue must be initialized before 
the output device despooler can be initialized. After both the 
queue and output device despooler are initialized, the queue can 
accept print jobs and the named printer is set spooled. 
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Notes 


No more than 16 print queues (including queues for applications 
processors) can be initialized. 


On RSX-11M-PLUS, no more than 16 batch queues can be initialized. 


These counts include the default PRINT and BATCH queues. 


7.2.1.2 INITIALIZE/PROCESSOR (QUE /SP) - This command creates, names, 
and starts an output despooler or batch processor. When you 
initialize an output despooler, this task "owns" a hardware device. 
This is setting the device spooled; a spooled device can be accessed 
by the Queue Manager. 


Formats 
DCL> INITIALIZE/processortype processorname/[/qualifier] 


MCR>QUE processorname:/SP[/sw[s]] 


DCL Processor Types MCR Function 
/ PROCESSOR /SP 

/PRINTER /SP 

/DEVICE /SP 

/BATCH_ PROCESSOR /BA 
/APPLICATIONS PROCESSOR /SP/EX 

DCL Qualifiers MCR Switches 
/FLAG_PAGE:n /FL:n 

/ LOWERCASE /LOW 
/UPPERCASE /NOLO 

/ FORMS :n /FO:n 

/ SHAREABLE /SHR 


Processor Types 


/PROCESSOR’ (/SP) 


/PRINTER (/SP) 

/DEVICE (/SP) 
The DCL processor types fall into three groups. One group 
consists of /PROCESSOR, /PRINTER, and /DEVICE. These three are 
synonyms. The effect of each is the same. The synonyms are 


provided to assure unambiguous commands and documentation. Use 
/PRINTER for line printers and /DEVICE for other output devices. 


If you use one of these three synonyms, a device-specific queue 
must exist before the output despooler task can be initialized. 
See Notes. 


The MCR /SP switch performs the same function. There are no 
synonyms in the MCR form of this command. A device-specific 
queue must exist before the output despooler task can be 
initialized. See Notes. 


/BATCH_PROCESSOR (/BA) 


This is the second DCL processor type. Use this processor type 
(or option) when initializing a batch processor. 
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/APPLICATIONS PROCESSOR (/SP/EX) 


This is the third DCL processor type. Use this processor type 
when the destination of the output is not a physical device, but 
rather some software application. Use /APPLICATIONS PROCESSOR 
when you are initializing a user-written output despooler for 
which the physical device is not currently in the’ system. This 
makes it possible for the Queue Manager to despool output to an 
applications task, to a network, or to some other instance of 
down-line loading. 


In MCR format, you must combine the /SP and /EX options. 
When you use this command in either form, the Queue Manager does 
not check for the existence of a physical device before 
initializing the processor. 

Parameter 

processorname 
Remember, the names of the device, processor, and queue are _ the 
same, and interchangeable. MCR users must include the colon 


( : ) but DCL users can omit it. 


You must initialize device-specific queues before you initialize 
the print processor with the same number. 
If initializing a batch processor, its name must be in the form 


DCL Qualifiers and MCR Functions 


These qualifiers and functions have meaning for initializing 
print processors only. 


With the exception of setting the number of flag pages, these 
qualifiers have no effect on the printed output of the printer 
being initialized. Rather, these qualifiers define the kind of 
print jobs the processor can accept. 


Different kinds of print jobs are established by the PRINT 
command that places them in the queue. 


/FLAG PAGE:n (/FL:n) 


This qualifier specifies how many flag pages are to precede jobs 
and files printed by this processor. The default is O and the 
value of n must be O, 1, or 2. 


If the processor is being initialized to accept special forms, 
you may want to set this qualifier to 0. 


If you wish, you can change the value set here with the /FLAG 
qualifier to the START/ command (/FL switch to /STA option). 


/LOWERCASE (/LOW) 


If you initialize a printer as lowercase, that printer will 
accept print jobs with lowercase or uppercase specified in the 
PRINT command. Normally, you should not use this qualifier 
unless the hardware involved has both the uppercase and lowercase 
character sets. 
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/UPPERCASE (/NOLO) 


If you initialize a printer as uppercase, that printer will not 
accept print jobs with lowercase specified in the PRINT command. 
Normally, you should not use this qualifier unless the hardware 
involved does not have the lowercase character set. This is the 
default. 


/FORMS:n (/FO:n) 
The value for n can range from 0 through 255. The default is O. 


These numbers are to be specified by your users in their PRINT 
commands. 


You should determine which forms will be used on your system and 
assign each a number. You should then edit the file 
LB:[1,24]LPPBLD.CMD to set up the forms table for the print 
processor to correspond to the numbers you have assigned to the 
forms. Then, you must build the processor. 


If the right forms are not in an available printer, their jobs 
will wait until the printer stops, the proper forms are put in 
place, and the printer is restarted with a new value for /FORMS 


(/FO). 


Forms differ by their length and width. Both values can be set 
in the forms table. 


Setting width is simply a matter of determining how many columns 
are needed to fill in the form. There are no standard widths for 
forms, but 80 and 132 are the most common. 


Setting length requires you to determine whether your forms are 
of a standard length. "Standard length" is any form length that 
can be set on your printing hardware. If the hardware can handle 
the form by setting a response to a form-feed character, then it 
is a standard length form, and the form feed is a "real," 
(hardware) form feed. 


If the form length cannot be set on the hardware, then it is a 
nonstandard length. In this case, the form feed must be replaced 
by an appropriate number of line feeds. This is called a 


"simulated," (software) form feed. 

The following table shows the forms requirements for a 
hypothetical installation. The form names describe different 
uses for these special forms, but the names have no significance 
otherwise. 

Form Assigned n Width Length Standard? 
Accordion 0 132 66 $4 
Paychecks 1 40 10 Y 
Invoices 2 80 66 Y 
Stationery 3 80 66 Y 
Moon Diary 4 22 43 N 
Star Log 5 112 113 N 

The forms table can be changed at LB:[{1,24]LPPBLD.CMD. This 


procedure is explained in the comments in this file. 
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As shipped, FORMS:0 is 66 lines long by 132 columns with real 
form feeds. FORMS:1 is 1 line long by 132 columns with simulated 
form feeds; FORMS:2 is 2 lines long by 132 columns with simulated 
form feeds; and so on through FORMS:66 which is 66 lines long by 
132 columns with simulated form feeds. The remaining FORMS:n 
entries are set to 1 line long by 132 columns with simulated form 
feeds. Thus, if you specify /FORMS:43, when the - printer 
encounters a form feed, it will count the number of lines on the 
page and subtract that number from 43. The printer will then 
reel off a number of line feeds equal to the difference. You may 
find this arrangement satisfactory if your installation rarely 
uses forms other than standard line-printer paper, but if you 
have more than one standard form, you will probably want to make 
the changes in the forms table entries. 


/SHAREABLE (/SHR) 


This qualifier establishes the processor as_ shareable. This 
means the physical device is not "owned" by a processor if it is 
not printing a job. Normally, the output processor attaches’ the 
device when it is initialized and no other job can access the 
device until it is detached. 


If you initialize the processor as shareable, the device is 
attached at the beginning of the QMG print job and detached at 
the end of the job, leaving the device free for other uses. 


Examples 


TOL STMITLAL TPE SPROCFSSOR LPO? 


MORSGUE LEG? /SP 


LPO: is set spooled. Jobs can be passed to it from the Queue 
Manager. 


You must initialize a device-specific queue named LPO before you 
can initialize the processor for device LPO:. 

YOR DO TNITTTALIZE SPRINTER LPYS/FLAG. PAGE EO 

MCORSQHE LFLI/SSP/FLIS 
This command initializes a print processor to control LPI: and 
specifies that jobs run on this printer will be preceded by two 
flag pages. Jobs specifying flag pages in the PRINT command will 
have two flag pages at the head of the job. 

HCL SINITIALLSE SPRINTER LPI /NOLOWER 

MURSQUE LPL /SP/NOLOW 
This command initializes a print processor to control LPI: and 


states that the printer will only accept jobs specifying 
uppercase in the PRINT command. 
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DCL>INI/BATCH.. PEORERSOR RAPS oe 


MCOROQUE BAPO! /BA 


This command created, names, and starts batch processor BAPO, on 
an RSX-11M-PLUS system. 


DCL OINI/PRO | PO/FL AG? 2/FORMS: O/LOWFR 
MCRSQUE LFOL/SP/FLE2/FOLO/7LOW 


This command creates, names, and starts print processor LPO. The 
printer has the lower-case character set. Jobs will have two 
flag pages when printed. 


Notes 


No more than 16 batch processors on an RSX-11M-PLUS system, or 16 
print processors (including applications processors) can be 
initialized. 


If you are initializing an output despooler that attaches a 
physical device, the system checks for the existence of the 
device and of its device-specific queue before the command is 
executed. Therefore, the following procedure must be followed. 


1. The device must be part of the current system. 


2. You must initialize a device-specific queue for the device 
before you initialize an output despooler of the same type 
and number. 


When you initialize an output processor, it is named and 
started and has its device-specific queue assigned to it. 


3. For each print processor, there must be a print queue, called 
the device-specific queue, with a corresponding name. The 
printer named LPO: is owned by the output despooler named 
LPO. There must also be a device-specific queue named LPO. 
The processor cannot be named until the device-specific queue 
has been initialized. This queue will be assigned 
automatically to the processor whose name it shares, but’ the 
device-specific queue can be deassigned and assigned 
elsewhere after initialization. 


This procedure does not apply to initializing batch 
processors or applications processors. Neither a physical 
device nor a device-specific queve is needed to initialize a 
batch processor or applications processor. 


There can also be print queues whose names do not’ correspond 
to output devices. These are called general queues. 


The lowercase/uppercase attributes have no effect on the nature 
of the printer's output. They do not cause jobs to be printed 
all uppercase. These qualifiers set up a "mask" that must be 
matched by the attributes of print jobs before they can be sent 
to the printer. A printer without the lowercase character set 
can be initialized lowercase and it will accept print jobs with 
lowercase specified in the PRINT command. This might be done if 
a printer with the lowercase character set was temporarily 
unavailable. As a general rule, however, you should only 
initialize printers with the characteristics they actually have 
to avoid confusion. 
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(The line printer driver does, however, affect the printer's 
output, through lowercase-to-uppercase translation. See the 
discussion of SET /LOWER in the RSX-11M/M-PLUS MCR Operations 
Manual, or the discussion of SET DEVICE JLOWER in the RSX-11M 
Command Language Manual or the RSX-11M-PLUS Command Language 
Manual.) 


DELETE/ (QUE /DEL) 


You can delete queues or processors. 


7.2.2.1 DELETE/QUEUE (QUE /DEL:Q) - DELETE/QUEUE deletes queues by 


name. 


Formats 


DCL>DELETE/QUEUE queuename/ERASE 


MCR>QUE queuename:/DEL:Q 


Parameter 


queuename/ERASE (/DEL:Q) 


This specifies the name of a queue to be deleted. Only a 
privileged user can delete a queue using this parameter. The 
default queues BATCH and PRINT cannot be deleted. 


If the queue has jobs in it, it will be marked for delete. When 
the last job leaves the queue, the queue itself is deleted. No 
new jobs can be entered. 


You cannot delete device-specific queues until after you have 
deleted the processor with the same number. See next section. 


Examples 


QOL OTELETE/QUPUF MONA/FRASE 
MCR>QUE MOMAC/STEL IO 


This privileged command deletes the queue named MONA if it is 
empty. If the queue has entries, it is marked for delete, and 
will be deleted as soon as the last job is removed from the 
queue. Note the colon in the queue name in the MCR example. 


7.2.2.2  DELETE/PROCESSOR (QUE /UNSP) - DELETE/PROCESSOR deletes print 
processors, output despoolers, or batch processors by name. The 
command also sets the device unspooled. 


Formats 


DCL> DELETE/processortype processorname 


MCR>QUE processorname: /UNSP 
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DCL Processor Types MCR Functions 
/ PROCESSOR /UNSP 
/PRINTER /UNSP 
/DEVICE /UNSP 
/BATCH PROCESSOR /UNBA 
/APPLICATIONS PROCESSOR /UNSP 

Parameter 

processorname 


For physical devices, the name of the processor is identical with 
the name of the physical device. Thus, the device LPl: is 
controlled by processor LPl:. DCL commands do not require that 
you include the colon (:), but you must include the colon in all 
MCR commands. 


Batch processors have names in the form BAPnnn, where nnn is’ one 
to three Radix-50 characters. 


Applications processors have names of six Radix~-50 characters. 
Processor Types 


/PROCESSOR (/UNSP) 


/PRINTER 

/ DEVICE 
The DCL processor types fall into three groups. One group 
consists of /PROCESSOR, /PRINTER, and /DEVICE. These three are 
synonyms. The effect of each is the same. The synonyms are 


provided to assure unambiguous commands and documentation. Use 
/PRINTER for line printers and /DEVICE for other output devices. 


If you use one of these three synonyms, the device-specific queue 
cannot be deleted until after the output despooler task is 
deleted. 
These distinctions do not apply in MCR. 

/BATCH_ PROCESSOR (/UNBA) i : 


This is the second DCL processor type. : Use this processor type 
when deleting a batch processor. © 


/APPLICATIONS PROCESSOR (/UNSP ) 
This is the third DCL processor type. Use this processor type 
when the destination of the output is not a physical device, but 
rather some software application. Use /APPLICATIONS PROCESSOR 
when you are deleting a user-written output despooler. 
Examples 
TE SIE Ca EP Re eh Ae 


MORE QR LRPot CUNSP 


This example deletes processor LPO, the owner of line printer 
LPO:. 


DCL>DELETE/BATCH PROCESSOR BAP2 


MCR>QUE BAP2:/UNBA 
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delete the batch processor 


The commands are equivale y the ba 
LUS system. Note the colon in the MCR 


named BAP2, on an RSX-11M- 
command . 


QCLSNELETE/FROCESSOR LFO 
NCLOOQELETE/QUEUE LPO/ERASE 


MCRSQUE LPO? /UNSF 
MCRSQUE LEO? /TEL SQ 


This example shows the order you must follow to delete a 
device-specific queue. 


Notes 
DELETE/PROCESSOR (/UNSP) counteracts INITIALIZE/PROCESSOR (/SP). 
For maximum clarity, operators using DCL should use the’ specific 


qualifiers /PRINTER and /DEVICE rather than the synonym 
/ PROCESSOR when deleting output despoolers. 


7.2.3 ASSIGN/QUEUE (QUE /AS:) 


ASSIGN/QUEUE (QUE /AS:) establishes a path from a queue to a 
processor. 


Formats 
DCL>ASSIGN/QUEUE queuename processorname 
MCR>QUE processorname:/AS:queuename 
Parameter 
queuename 
This specifies the queue that is to be assigned to the processor. 
processorname 


This specifies the processor to which the queue is to be 
assigned. 


When assigning queues to output devices, use the the device name 
in the form ddnn:. 


Notes 


This command can be used to redirect output from one processor to 
another. 


Other uses include grouping related processors, such as plotters, 
under a single queue. 


7.2.4 DEASSIGN/QUEUE (QUE /DEA) 


DEASSIGN/QUEUE (QUE /DEA) counteracts ASSIGN/QUEUE (/AS). It is used 
to eliminate the path from a queue to a processor. 
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Formats 
DCL>DEASSIGN/QUEUE queuename processorname 
MCR>QUE processorname: /DEA:queuename 
Parameters 
queuename 


This specifies the queve that is to be deassigned from the 
processor. 


processorname 


This specifies the processor from which the queue is to _ be 
deassigned. 


When deassigning queues from output devices, use the device name 
in the form ddnn:. 


7.2.5 STOP/ (QUE /STO) 


STOP/ (/STO) is used to stop queues, the Queue Manager, or a 
processor. 


7.2.5.1 STOP/QUEUE (QUE /STO:QUE) - STOP/QUEUE stops queues. 

Formats 
DCL>STOP/QUEUE queuename 
MCR>QUE queuename:/STO:QUE 

Parameter 

queuename 
This specifies the queue to be stopped. Following the command, 
no jobs will be taken from the queue, but jobs can still be added 
to the queue. 
If a job is active at the time this command is issued, the job 
will be allowed to complete processing but no further jobs will 


be dequeued. 


Note the colon (:) in the MCR form of the command. 


7.2.5.2 STOP/QUEUE/MANAGER (/STO:QMG) - STOP/QUEUE/MANAGER (/STO:QMG) 
stops the Queue Manager and deletes all processors, whether batch 
processors or Output despoolers. 

Formats 


DCL>STOP /QUEUE/MANAGER[ /ABORT ] 


MCR>QUE /STO:QMG[ :AB] 
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Notes 


If you issue this command without the /ABORT (:AB) qualifier, QMG 
is marked for stop. As soon as all currently active jobs on all 
processors are done, QMG will stop. No more jobs can be entered 
in the queue. See also example in Section 7.2.6.2. 


If you include the /ABORT (:AB) qualifier, all active jobs are 
held immediately and QMG exits without further delay. 


7.2.5.3 STOP/PROCESSOR (QUE /STO) - STOP/PROCESSOR (/STO) stops a 
processor. 


Formats 


DCL>STOP/processortype processorname[ /qualifier] 


MCR>QUE processorname:/STO[ :opt] 


DCL Processor Types MCR Functions 
/ PROCESSOR /SsTO 
/PRINTER /STO 
/DEVICE /STO 
/APPLICATIONS PROCESSOR /sTto 
/BATCH PROCESSOR /STO 
DCL Parameter Qualifiers MCR Options 
/PAUSE <no equivalent> 
/JOB_END :EOJ 
/FILE_END : EOF 
/ ABORT :AB 
Parameter 
proce ssorname 


When stopping print processors, use the device name in the form 
ddnn:. 


This command has no effect on the status of jobs in queues, but 
no jobs will be dequeued while the processor is stopped. 


Processor Types 


/PROCESSOR (/STO) 
/PRINTER 
/DEVICE 


The DCL processor types are synonyms. The effect of each is the 
same. These synonyms are provided to assure unambiguous commands 
and documentation. Use /PRINTER for line printers, /DEVICE for 
other output devices and /BATCH PROCESSOR for batch processors. 
MCR users use /STO across the board. 


/BATCH_PROCESSOR (/STO) 


Use this processor type when stopping a batch processor. 
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/APPLICATIONS PROCESSOR (/STO) 


Use this processor type when the destination of the output is not 
a physical device, but rather some software application. Use 
/APPLICATIONS PROCESSOR when you are stopping a_ user-written 
output despooler. 

Qualifiers 


Only one qualifier is permitted. The choice of qualifier here 
affects the restarting of jobs when the processor is started 
again. 

/PAUSE <no equivalent> 
This is the default; it causes the processor to stop at the end 
of the current line. There is no MCR qualifier; /STO is 
sufficient. 


/JOB_END (:EOJ) 


This qualifier causes the processor to stop at end of the current 
job. 


/FILE_END (:EOF) 


This qualifier causes the processor to stop at end of the current 
fi Le. 


/ABORT (:AB) 


This qualifier causes the processor to stop immediately. The 
current job is held in its queue. 


Notes 
This command is counteracted by START/PROCESSOR (/STA). You 
cannot issue START/PROCESSOR (/STA) until the processor actually 
stops. 


7.2.5.4 STOP/ABORT (QUE /KIL) - STOP/ABORT (/KIL) deletes the active 
job on a given processor. Privileged users can delete any job; 
nonprivileged users can delete their own jobs. You do not need to 
know the queue name or job name to delete the job, only the name of 
the processor. 


Formats 
DCL>STOP/ABORT processorname 
MCR>QUE processorname:/KIL 
processorname 
This specifies the processor whose active job you wish to delete. 
Note that the MCR command format requires a colon (:) after the 


processor name. 


You can stop jobs running on any processor under the control of 
QMG, including RSX-11M-PLUS batch processors. 
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Examples 


QOL SS TOR /ARORT 
Frocesggark Leg 


This example shows how to stop a print job on LPO: The currently 
active job is deleted from the queue and the next eligible job is 
queued. 


Notes 


Use this command to quickly stop a processor, such as a line 
printer printing nothing but form feeds. 


As soon as the active job is deleted, QMG passes the next 
eligible job to the processor. The processor has not been 
aborted or killed, only the active job on that processor. 


You can also delete the active job on a card-reader processor 
with this command. 


7.2.6 START/ (QUE /STA) 


START/ (QUE /STA) is used to start a queue, the Queue Manager, or a 
processor. START/ (QUE /STA) counteracts STOP/ (/STO). 


7.2.6.1 START/QUEUE (QUE /STA) - START/QUEUE (QUE /STA) starts a 
queue. 


Formats 
DCL>START/QUEUE queuename 
MCR>QUE queuename:/STA 
Parameter 
queuename 
This specifies the queue to be started. This command starts a 


queue that has been’ stopped. Note the colon (:) in the MCR 
format. 


7.2.6.2 START/QUEUE/MANAGER (QUE /STA:QMG) - START/QUEUE/MANAGER (QUE 
/STA:QMG) starts the Queue Manager, initializes the default queues 
PRINT and BATCH, and creates the queue file LBO:[1,7]JQUEUE.SYS if it 
does not exist. The command also clears all queue assignments. If 
the queue file was intact, all queues will still contain their jobs, 
but will not be assigned to processors. 


Formats 
DCL>START /QUEUE/MANAGER 


MCR>QUE /STA:QMG 
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. 


Examples 
Gl, START / QUEUE /MANAGER 
NR oe KS Ta CONG 
Starts Queue Manager. Initializes the default queues PRINT 
BATCH, if they are not already initialized. Clears 


assignments of queues to processors. 


Any jobs that were active at the time the Queue Manager 


and 
all 


was 


stopped will be held when the Queue Manager is started again. 
All other jobs retain the status they had when QMG was stopped. 


All processors must be reinitialized. 


The default queue BATCH is initialized on RSX-11M systems as well 


as RSX-11M-PLUS, but it is neither accessible nor displayed. 
Cob STAR /QUEYFE AMANAGBER 
MOR SUE “STO3 QNG 


With this command, the Queue Manager is stopped, and 
processors are deleted. 


Neh START /GUETE “MANAGER 
AGE OQUE “STAAL QMG 


This command clears all assignments of queues to processors. 


DCL: LALTIALLZE/ERINTER LPS 
(OLD IMITIAL LZE PRINTER LEA 

Ch > INTTLIALIZE/BATCH PROCESSOR BAFO 
OCLUINITIALIZE/BATCH. PROCESSOR RAFI 
DCL. ASSTGON/QUENE FRINT LPG 

UCL > ASS IONS GUPUP PRINT LP4 
UCLEASSTGN/QUENE BATCH BAFO 

UCL PASSTUN/QUEUF BATCH BAFL 


MGR GUHE LPO? SSF 

MORE AUE Leesa 

MOP: GUE BAPOS/EA 

MOR? QUE BAPLY/BA 

MOR SWE LPO? ZASTERINT 
MORSE OUP L PLS /AST PRINT 
HORS QUE BAPO? /ASS BATCH 
MCR SCUE BARLEY /ASTRATCH 


These commands recreate the network of queues and processors. 
that RSX-11M systems have no batch processors. 


DGLoRELEASE/JOB PRINT BOBO 
MORE GUF FRINTIROBO/SREL, 


This command releases a held job that was active at the time 
system crashed. 


all 


Note 


the 
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7.2.6.3  START/PROCESSOR (QUE /STA) - START/PROCESSOR (QUE /STA) 
starts a batch processor or output despooler. 


Formats 


DCL>START/processortype processorname [/qualifier[s]] 


MCR>QUE processorname:/STA[:opt[s]] 


DCL Processor Types DCL Qualifiers 
/ PROCESSOR / FORMS :n 
/PRINTER - /FLAG:n 
/DEVICE . /CONTINUE 
/BATCH_ PROCESSOR /RESTART 


/APPLICATIONS PROCESSOR /NEXT_JOB 
/TOP_OF_FILE 
/BACKSPACE :n 
/FORWARDSPACE:n 
/AT_PAGE:n 
/ ALIGN 


MCR Options 


/FO:n 

/FL:n 

<no equivalent> 
:NE 

:RES 

:PA:0O 

:BA:zn 

sFWen 

:PAzn 

/AL 


Parameter 


processorname 


ddnn: 


This specifies the processor to be started. When starting a 
stopped output processor, use the device name in the form ddnn:. 


Processor Types 


/ PROCESSOR 

/PRINTER 

/DEVICE 

/BATCH PROCESSOR 
/APPLICATIONS PROCESSOR 


These are DCL synonyms. The effect of each is the same. These 
synonyms are provided to assure unambiguous commands.) and 
documentation. Use /PRINTER for line printers, /DEVICE for other 
output devices, /BATCH PROCESSOR for batch processors, and 
/APPLICATIONS_PROCESSOR for applications processors. In MCR 
format, use the /STA option. 


Qualifiers 


Some qualifiers have meaning for starting either batch or print 
processors, and some have meaning for print processors only. See 
descriptive text. 
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This field is restricted. You can include either /FORMS: (/FO:) 
or /FLAG: (/FL:) or both, or you can include any one of the 
remaining qualifiers, if permitted. 


/FORMS: (/FO:) and /FLAG: (/FL:) have meaning for print 
processors only. 


/FORMS:n (/FO:n) 


This overrides the forms value set when the processor was 
initialized. The value n can be any number from 0 through 256. 


/FLAG:n (/FL:n) 


This overrides the flag value set when the processor was 
initialized. 


When the processor starts again, the Queue Manager sends the next 
job that matches the attributes of the processor. 


/CONTINUE 


This specifies that the processor carry on from wherever it was 
stopped. This is the default. MCR format requires no switch. 


/RESTART (:RES) 


This specifies that interrupted jobs be restarted from the 
beginning of the file that was being processed when the processor 
was stopped. This qualifier affects only jobs that were ACTIVE 
at the time the processor stopped. 


This qualifier may conflict with the desires of your users who 
have specified /NORESTART in their PRINT or SUBMIT commands. 
This qualifier causes such jobs to be restarted at the start of 
the file being processed when the processor was stopped. You 
should check the queue display for such jobs before using this 
qualifier. The /CONTINUE (default) qualifier will not affect 
such jobs. 


The action of this qualifier further depends on the qualifier to 
the STOP/ (/STO) command that stopped the processor in the first 
place. 


If the qualifier was /PAUSE (the default for /STO), then any jobs 
active at that time will be restarted at their beginning. 


If the qualifier was /FILE END (:EOF), then any jobs active at 
that time will be restarted at their beginning, unless the active 
file was the last one in the job. 


If the qualifier was /ABORT (:AB) (or if the system crashed), the 
current active job was held in its queue, so_ the restart 
qualifier will have no effect. 


Likewise, if the qualifier was /JOB_END, (:EOJ) there will have 
been no current job, so the restart qualifier will have no 
effect. 

/NEXT_JOB (:NE) 


This specifies that the processor start at the beginning of the 
next job. 
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/TOP_OF FILE (:PA:0) 


This specifies that the processor start at the top of the current 
file in the current job. 


The qualifiers /CONTINUE (the default for /STA), /RESTART (/RES), 
/NEXT_JOB (/NE), and /TOP_OF FILE (PA:0) are appropriate for both 
print and batch processors. 

/BACKSPACE:n (:BA:n) 


This specifies that the processor start n pages back in the 
current job. 


/FORWARDSPACE:n (:FW:n) 


This specifies that the processor start n pages forward in the 
current job. 


/PAGE:n (:PA:n) 


This specifies that the processor start at specified page in the 
job that was active when the processor was stopped. 


These page-related qualifiers have meaning for print processors 
only. They will have no effect unless the user specified a page 
length qualifier in the PRINT command. 

/ALIGN (:AL) 


This informs the print processor that the paper in the line 
printer is currently at the top of a form. It is used when you 
have stopped the print processor to change forms. The print 
processor maintains a count of how many lines it has gone down on 
a form. The /ALIGN (/AL) qualifier clears that count for new 
forms. 
Examples 
ORL OSTART/FPRINTER LPO 


MORD RUE ERO? SSTA 


This example starts print processor LPO:. Printing continues 
from the point at which it was stopped. 


OCLoE START /PRINTER LFO/FILAGE2 

MCREQUE LFOL/SSTA/FLI2 
This example starts print processor LPO:. The processor will put 
two flag pages at the head of the job and at the head of each 
file if the user specifies flag pages in a PRINT command. 

TCL>START/BATCH PROCESSOR BAPO 

NCR: QUE BAFOS/STA 


This example starts batch processor BAPO. Batch processing 
continues from the point at which it was stopped. 
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ICL START/BATCH BAPO/CONTINUE 
MCR>QUE RAPOL/STA facet 

The two examples are equivalent. 
DCL? START/PRINTER LPA/RESTART 
MCRDQUE LPAL/STALRES 


This example starts print processor LPl:. The job active at 
time the processor was stopped is restarted. 


Notes 


You should choose with care between the /RESTART (:RES) 


the 


and 


/CONTINUE (MCR default) operations. A restart may conflict with 


the desires of users with print or batch jobs active at the 
a processor is stopped. 


time 


Users can specify /NORESTART (/-RES) in their PRINT or SUBMIT 
commands. If a print or batch job with this attribute is active 


when the processor is stopped, and you start the processor 


with 


the /RESTART (:RES) qualifier, you will be restarting the jobs at 
the top of the file that was being processed when the processor 


was stopped, which the user did not want to happen. 
/CONTINUE (MCR default) qualifier will continue such jobs as 
user expected. 


If you are restarting a processor to handle special forms, 


The 
the 


you 


will probably want to set the /FLAGS (:FL) attribute to 0 to 


avoid having a banner page printed on your special forms. 


CHAPTER 8 


THE SHUTUP PROGRAM 


SHUTUP is the system program that enables orderly shutdown of an 
RSX-11M or RSX-11M-PLUS system. SHUTUP sends warning messages, aborts 
nonprivileged tasks, and dismounts devices on the system. 


8.1 PREREQUISITES TO RUNNING SHUTUP 


To shut down a system using SHUTUP, the following tasks must _ be 
installed: 


@ INDIRECT, the MCR Indirect Command Processor 

e ACS, if dynamic checkpoint space is established 
e BYE, if multiuser protection support is included 
@e DMO, if there are any mounted devices 


e ELI, if error logging is active 


e ACC, in an RSX-11M-PLUS system that includes Resource 
Accounting es oes : 


If LB:[1,2]SHUTUP.CMD is present, you may want it to install ACS, BYE, 
DMO, ELI, and ACC. See Section 8.5. 


8.2 INVOKING SHUTUP 
Invoke SHUTUP from a privileged terminal as follows: 
SRL @SHUTUP (RET 


On RSX-11M systems, SHUTUP displays the following message when 
invoked: 


RSX-1iM SHUT TOWN PROGRAM 


On RSX-11M-PLUS systems, SHUTUP displays the following message when 
invoked: oe 


RSX-LIM-FLUS SHUT DOWN PROGRAM 
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8.3 SHUTUP INPUT 

SHUTUP prompts for the number of minutes as follows: 
1. Number of minutes to wait before the system is shut down 
2. Number of minutes between warning messages 
3. Number of minutes before disabling logins 


If you specify less than 4 minutes to wait before shutdown, SHUTUP 
does not ask the last 2 questions. Instead, SHUTUP sets the interval 
between messages to 1 minute and disables logins immediately. 


The number of minutes between messages must be greater than zero and 
less than the number of minutes before shutdown minus three. If you 
specify either value incorrectly, SHUTUP rejects your answer and 
reprompts. 


The following is an example of SHUTUP prompts and user input on an 
RSX-11M system: 


Enter minutes to wait before shut downs i @eD 
Enter minutes between messades ? 3 GED 
Enter minutes to wait before disabling logins? 5 


If you are using an RSX-11M-PLUS or Micro/RSX system, SHUTUP asks an 
additional question, which is shown in the following example: 


Enter minutes to wait before shut down! 15 GD 

Enter minutes between messades! 3 GED 

Enter minutes to weit before disabling Indinst 5 

Resson for shutdown (<CR> for mane)? FIFLT SERVICE PM GED 


After receiving your input, SHUTUP asks for confirmation as follows: 


OK toa shubeclown? CLY/N7? 


SHUTUP terminates without taking any action if your response to the 
question is N. If your response is Y, SHUTUP sends warning messages 
to terminals. Section 8.4 explains the messages. 5 


8.4 SHUTUP OUTPUT 


SHUTUP sends warning messages to terminals. If the system does. not 
support multiuser protection, SHUTUP sends warning messages to all 
terminals. If the system does support multiuser protection, SHUTUP 
sends warning messages only to logged-in terminals. On multiuser 
systems, a terminal set to NOBROADCAST receives the warning messages 
only during the last five minutes before shutdown. 


SHUTUP sends the following warning messages: 


Please finish wer 15 minutes before shutdown ~~ WALNUT Reason for 
shartectowrss Fieleh Serviwe FM 


Three minutes later, SHUTUP sends another message: 


Please finish ues 1? minutes before shutdawn ~-- WALNUT 
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The messages include a 6-character name that is a DECnet node name (if 
DECnet is active) or the system name that was selected during system 
generation (if DECnet is not active). In the previous messages, 
WALNUT is the 6-character name. 


SHUTUP continues to issue the warning messages at the interval 
specified. When three minutes remain before system shutdown, SHUTUP 
changes the interval between messages to one minute. 


If the system supports multiuser protection and the specified delay 
before disabling logins has expired (measured from the time SHUTUP is 
started), SHUTUP displays the following message on the invoking 
terminal: 


All further logins are disabled 


After SHUTUP logs out all terminals, aborts all nonprivileged tasks, 
and dismounts all devices, it displays the following message on the 
invoking terminal: 


SHUTUF ofrerstian comelete 
SHUTUP then halts the processor. 


At this point, you can either bootstrap another system or resume 
operation of the current system by pressing the continue switch on the 
CPU console. After you press the CONT switch (continue), logins are 
enabled and the following message appears on the invoking terminal: 


Logins 3P°e mow enadoled 


To continue operation of the current system, you must mount’ the 
devices and follow normal system startup procedures. 


8.5 THE SHUTUP.CMD FILE 


The indirect command file LB:[1,2]SHUTUP.CMD is for user-specific 
functions. SHUTUP submits the file, if present, to the Indirect 
Command Processor for execution. The SHUTUP task-build file specifies 
the amount of time (the time-out interval) that SHUTUP.CMD has to 
execute. The default time-out interval is 120 seconds or 170{octal). 
It is possible to change the time-out interval for SHUTUP.CMD in the 
task-build file. 


On unmapped RSX-11M systems, the task-build file is [1,20]SHUBLD.CMD. 
On mapped RSX-11M systems, the file is [1,24]SHUBLD.CMD. 


For RSX-11M-PLUS systems, the task-build file is [1,24]SHUBLD.CMD. 


If the timeout interval expires and SHUTUP.CMD is not finished, SHUTUP 
asks if you want to wait for SHUTUP.CMD to finish. For example: 


Command (AT.) Timeout - Continue waiting? [Y/N]: 


If you enter N, SHUTUP continues without waiting any longer. If you 
enter Y, SHUTUP waits an additional 30 seconds. SHUTUP continues 
without waiting any longer if SHUTUP.CMD has not finished at the end 
of the 30 seconds. 
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You may want SHUTUP.CMD to install ACS, BYE, DMO, ELI, and ACC (these 
tasks must be installed to enable SHUTUP to execute properly). If you 
have an RSX-11M-PLUS system, SHUTUP.TSK will install ACS and ELI. If 
DECnet is installed on your system, you may use SHUTUP.CMD to shut 
down the network. 


The following is an example of a SHUTUP.CMD file: 


*THIS SHUTUF.CMM FILE INSTALIS ELT 
yANT ACS TF THEY ARE NOT INSTALLED» 
gANT ALSO ACTIVATES @ COMMAND FILE TO 
ISHUT OOWN THE NETWORK TF THE NETWORK 
91S ACTIVE. 


a 


y 


sENARLE SUBSTITUTION 


+TFNINS «+E T INS $ELT 
eTFNINS 4.5ACS INS $ACS 


*TFNACT NETACRE .GNTA 26 
@LBIE 1s SINE TSTOR 


ry 4 
Ot 


8.6 RSX-11M SYSTEM SHUTDOWN 
The following sections describe the shutdown procedure for RSX-11M 


systems. An annotated example of a system shutdown supplements the 
description. 


8.6.1 RSX-11M System Shutdown Procedure 


When the delay before system shutdown expires, SHUTUP performs the 
following functions: 


1. Logs out logged-in terminals (multiuser protection systems 
only) 


2. Stops the Console Logger (if active) 
3. Redirects the console terminal to the TI: of SHUTUP 


4. Submits the indirect command file LB:[1,2]JSHUTUP.CMD (if 
present), to the Indirect Command Processor for execution 


5. Stops the Queue Manager (if active) 

6. Stops the Error Log Task (ERRLOG) (if active) 

7. Deallocates checkpoint space and dismounts devices 
8. Halts the processor 


At this point, you can either bootstrap another system or resume 
operation of the current system. 
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8.6.2 Beampie of an RSX-116 ‘System Shutdown — 


The eakiger is an example | of an ‘RSX-11M system shutdown: 


>RUN $SHUTUP 
>RSX-11M SHUT 


Enter minutes 
Enter minutes 
Enter minutes 
OK. to shutdown? CY/NI3 
“14- -nEC~85. 16335 Please 
14-DEC- 85, 143 38 Please 


AlL pavther: losing are 


14- -NEC- RS 16340 Please 


14-UEC-85 14342 


Please 
LA-DEC-85 16143 
14-DEC-85 16244 
14~NlEC-85 16145. 
ney /COLOG=0FF 1) 


BLEIC1+21SHUTUP 2) 
SINS $ELI 

>INS $ACS 

»@ SEDF? 


aue /STOLONG o 


“ELL /NOLOS @ 


“acs NROL/BLKS=0. @ 


Flease fini 


Sustem 


ROWN PROGRAM 


Y GD 


finish 


to wait before shutdown! 
between messades} 2 
to wait before disabling lodins: 5 


3 


Wes 


finish urs 7 


finish 


finish. 


Please finish weer” 


16246101 ERRLOG -- Erron Lodging 


AMP OO 


cisahled 


tps 3 


to 


10 @ 


minutes 


minutes 


minutes: 


“minutes 


ACS -- nee ass file HOW inactive ee 


ane DROS TEV _ 


wee ~~ Susten disk heing diawpunted 


-- SYSTEM 
310 


DMO | 
16 147 axe NBOL 
nMO Nsot DEV o@ 

DMO 


dismounted from DBOS 
~ ‘Dismount econmrlete 


DMO) == SYSTEM flismounted from DSO! 


ay ESTA7T EO #EK TSO 


oe 


SHUTUP operation complete e 


*KX Final 


== Warning -_ Techs ineiwiied from S03 
KKK Finel 
~— Hi swount complete 


10 minutes before 


hefore 


berore 


before 


before 


Cate 


dismount 


GED 


shutdown 


shutdown - 


shutdawr 
shutdown 
shutdawn 


shutdown 


ie 


CASHEW 


CASHEW 


CASHEW 
CASHEW 
CASHEW 


CASHEW 


dismount initiated xx 


initiated #xx* 
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To shut down the system in this example, SHUTUP performs as follows: 
@ Stops the Console Logger. 
@ = Invokes the indirect command file LB:[1,2]SHUTUP.CMD. 


SHUTUP.CMD installs ELI and ACS. The @<EOF> message 
indicates the end of the command file SHUTUP.CMD. 


Stops the Queue Manager. 
Runs the task ELI to terminate the Error Log Task (ERRLOG). 
Deallocates checkpoint files on DBO:. 


Dismounts the disks on DBO: and DSO:. 


©9ooe0d } 


Displays a message when SHUTUP has finished executing. 


8.7 RSX-11M~PLUS SYSTEM SHUTDOWN 
The following sections describe the shutdown procedure for 


RSX-LIM~PLUS systems. An annotated example of a system shutdown 
supplements the description. 


8.7.1 RSX-11M-PLUS System Shutdown Procedure 


When the delay before system shutdown expires, SHUTUP performs the 
following functions: 


1. Stops the Console Logger (if active) 
2. Redirects the console terminal to the TI: of SHUTUP 


3. Submits the indirect command file LB:[1,2]SHUTUP.cMD (if 
present) to the Indirect Command Processor for execution 


4. Logs off logged-in terminals (multiuser protection systems 
only) 


5. Stops the Queue Manager (if active) 

6. Stops Resource Accounting, if Resource Accounting is active 
7. Stops the Error Log Task (ERRLOG) (if active) 

8. Checkpoints all read/write commons 

9. Deallocates checkpoint space and dismounts devices 
10. Halts the processor 


At this point, you can either bootstrap another system or resume 
operation of the current system. 
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To shut down the system in this example, SHUTUP performs as follows: 


0 


690000 


Invokes the indirect command file LB:[1,2]SHUTUP.CMD. 


SHUTUP.CMD installs ELI and ACS. The @<EOF> message 
indicates the end of the command file SHUTUP.CMD. 


Stops the Queue Manager. 

Stops Resource Accounting. 

Runs the task ELI to terminate the Error Log Task (ERRLOG). 
Deallocates checkpoint files on DB?7:. 

Dismounts the disk on DB7:. 

The Virtual option, /LOCK=V, is privileged. When you specify 
the Virtual option, the DISMOUNT command does not clear 
volume as valid and does not spin down the disk. (Refer to 
the RSX-11M/M-PLUS MCR Operations Manual for additional 


information. 


Displays a message when SHUTUP has finished executing 


CHAPTER 9 


TERMINAL EMULATION AND FILE OPERATIONS WITH OTHER SYSTEMS 


9.1 INTRODUCTION 


A local Micro/RSX terminal can log in to and conduct an interactive 
session with an external computer system. This session is established 
using the Data Terminal Emulator (DTE). The external system can be an 
RSX-11M or RSX-11M-PLUS system, a VAX/VMS system running VAX-11l RSX, a 
Professional Personal Computer, or another Micro/RSX system. Once a 
local Micro/RSX terminal is logged in to an external system, the 
external system becomes the host system. The host system views 
Micro/RSX as remote. During an interactive session, files can be 
transferred between the host system and Micro/RSX. Files are 
transferred using the Micro/RSX File Transfer Utility (MFT). 


The following two conditions must exist for terminal emulation and 
file transfer to be operational: 


1. The two computers must be connected. 


2. The DTE software must be installed on the local Micro/RSX 
system, and MFT must be installed on the host system. 


Refer to Sections 9.1.1 and 9.1.2 for more detailed information. 


9.1.1 Connecting Two Computers 


The two computers can be connected either on-site or at remote’ sites 
through an asynchronous serial line. A Micro/RSX system is connected 
to an on-site external system by a cable and to a remote system by 
DFO3 modems and a telephone line. In either case, there is a 
dedicated line between the two systems that establishes the ports at 
each end of the line, assigned specifically for terminal emulation and 
data transfer. 


A direct hardwired connection between two systems can be established 
by plugging one end of a cable into the communications port in the 
back of the local system unit, and the other end of the cable to a 
host system. A permanent connection can also be established by using 
a DIGITAL Model H312A null modem cable and two standard EIA RS-232 
connectors. When the two systems are directly connected with a cable, 
the terminal characteristics of the port at the local Micro/RSX system 
should be set to SLAVE and NOECHO. This prevents the transmission of 
extraneous noise signals when the port is idle (disconnected from 
terminal emulation). Noise signals can create intersystem echo loops 
that seriously affect system performance. 
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Transmission speed between systems varies depending on the systems 
involved. Variations are based on the following: 

@ Processor type 

@ Interface type 

e System load 

e Distance between systems 


@e Terminal support (use of higher baud rates requires that the 
remote system support XON/XOFF protocol) 


If XON/XOFF is present, your terminal may run at a speed lower than 
that of the physical connection. For consistent performance, use a 
baud rate of 2400 for Micro/RSX. 


The following figures show typical configurations for a Micro/RSX 
system. 


User Terminal 


pe er SECTS OY Local PDP-11 
Micro/RSX or VAX 
System System 


Y y 


DTE Program MFT Program 


Connecting Ports 


(both set to same baud rate) 
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Figure 9-1 Terminal Emulation with an On-Site System 
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Figure 9-2 Terminal Emulation with a Remote System 


In these example configurations, when the local Micro/RSX user 
terminal (TT3:) is in terminal emulation, the following conditions 
exist: 

e@ TT3: is connected to port TT5: using the DTE software. 


e Port TT5: is connected to port TT30: in a PDP-1ll system. 
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@e Port TT5: is a connector on a DZV11. 
e Port TT30: is a connector on a DZll. 
Note that port TT5: is set using the following command line: 


* SFT TERMINAL TTS3/S8SL AVE /NOFCHO 


9.1.2 Location of DTE and MFT 


There are two separate programs that support Micro/RSX terminal 
emulation and file transfer. One resides in the local Micro/RSX 
system and the other resides in the host system. DTE, which is in the 
Micro/RSX system, establishes the local terminal as an emulated 
terminal. Establishing terminal emulation means connecting a_ local 
Micro/RSX terminal to an external system so that the local Micro/RSX 
terminal can be logged in as a user of the host system. 


The other program is MFT which interfaces with DTE when file 
operations are initiated at a local terminal. The MFT software is 
executed on the external computer system (the host) that is connected 
to the Micro/RSX system. 


DTE and MFT tasks are separate tasks that work together, but execute 
on two physically different systems. Also, note that all user key-ins 
are done at a terminal connected to the local Micro/RSX system. 


9.2 ESTABLISHING TERMINAL EMULATION 


Once you have determined that the two specified computers are 
connected and that both DTE and MFT are installed on their respective 
systems, you can establish terminal emulation. To establish a 
connection between Micro/RSX and another system, use the following 
command line: 


SET HOST/DTE device: /MUTE 


where device is the Micro/RSX device and unit specification of the 
terminal port used for terminal emulation. Specifying the /MUTE 
qualifier ensures that the terminal is set to SLAVE and NOECHO upon 
exiting from terminal emulation. 


The following command example establishes terminal emulation: 
$ SET HOAST/OTE TISt /MUTE 


This DCL command runs the DTE task, which establishes terminal 
emulation by connecting your terminal to port MTT5:. When data 
terminal emulation is terminated, port MTT5: is set to SLAVE and 
NOECHO. After you type this command (and follow it with a RETURN), 
you are connected to the host system. You can then log on as ae user 
of that system and use the file transfer utility (see Section 9.3). 


To terminate emulation, type the LOGOUT command from the host’ system. 
Then, press and hold the control key (CTRL) and type a P character. 
The following message is displayed: 


ANTE-S-EMUEXIT, Emulation exiting... Flease wait 


You are then returned to command level execution at the local 
Micro/RSX system. 
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NOTE 


Be sure that you log out from the host system before 
exiting terminal emulation. If you are in terminal 
emulation and press CTRL/P before logging out from the 
host system, the terminal connection is returned to 
the local Micro/RSX system. The host system remains 
logged in to your account. Under these conditions, if 


another user initiates terminal emulation, that user 
will be logged in to the host system under your 
account. 


To use DTE from the system's console terminal, you 
must first disable the console On-Line Debugging Tool 
(ODT). Both console ODT and DTE use the CTRL/P 
character. 


9.2.1 DCL Command Syntax 


The DCL SET HOST/DTE command qualifiers provide options that allow you 
to do the following: 


@ Dial out to the remote system through the DFO3 modem 
e Specify the terminal as mute (SLAVE/NOECHO) on termination 
e Display the version of the DTE task 
The SET HOST/DTE command line is as follows: 
SET HOST/DTE device:[/options] 


The options are as follows: 


/DIAL="..." 

Allows the specification of a dial command string for the DFO3 
modem. The string may consist of any of the digits O through 9, and 
the equal sign (=). The equal sign indicates that another dial tone 


is expected (for example, when you dial from an internal telephone 
system to an outside telephone number). 


/MUTE 


Specifies whether DTE should alter certain device characteristics 
prior to exiting. The default is to return all of the device 
characteristics to their original states. However, if the device 
is set NOSLAVE/ECHO, it is possible that noise characters can 
create intersystem echo loops, which can severely affect 
performance. Therefore, it is recommended that either the device 
be set to SLAVE/NOECHO when it is idle (DTE will change these 
characteristics), or that the /MUTE option be specified, which 
will set the device to SLAVE/NOECHO when DTE exits. 


/VERSION 


Displays the version of the DTE task. 
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9.2.2 Examples 
Following are examples using the SET HOST/DTE command. 


$ SET HOST/UTE TT40% 


This example invokes DTE to establish terminal emulation using 
terminal TT40:. 


& SET HOST/ITE TTSOL/NTAL="S550R837" 


This example initiates terminal emulation using terminal TT50:, after 
directing the DFO3 modem to dial the specified number and establish a 
modem connection. 


$ SET HOST/UTE TITAS /MUTE 


This example establishes terminal emulation using terminal TT25:, and 
sets the terminal characteristics to SLAVE/NOECHO on termination. 


9.3 PERFORMING FILE OPERATIONS 


The MFT utility is used to delete and transfer files between a 
Micro/RSX system, using terminal emulation and the host system that 
the local Micro/RSX is logged in to. Special code in the DTE task is 
used to identify and perform local file operations requested by the 
MFT task. File transfer is performed using an error detection and 
correction algorithm to ensure data integrity. The speed of file 
transfer varies with the processor and interface types, system load, 
and software. 


NOTE 


Support for variable typeahead buffer size allows for 
higher transfer rates. 


Your local terminal is locked out during file transfer operations to 
prevent interference with the data transfer between the two systems. 
You are returned to terminal emulation when the file operation 
completes. 


The command syntax used to perform file operations depends on the host 
operating system. 


9.3.1 MCR Command Syntax 
If the host system is an RSX-11M or RSX-11M-PLUS system, or a VAX/VMS 
system running VAX-1ll RSX, you use MCR commands to execute MFT as 
follows: 

>MFT 
The host system responds with the following: 


MFT> 
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You can now copy files from one system to the other, in either 
direction. To do this, use the following syntax to indicate the files 
that you wish to copy: 


MFT> to_file[/REM]=from_file[/REM] 


where: 
to file The output file or where the file is being copied 
to. 
from file The input file or where the file is being copied 
from. 
/ REM Means remote; is used to indicate that the file is 


on the local Micro/RSX system that is remote to the 
host system. 


If you want to copy from the host to the Micro/RSX system, the syntax 
is as follows: 


>MFT MESSAGE. TXT/REM=HOST.TXT 


If you want to copy from the Micro/RSX system to the host, the syntax 
is as follows: 


>MFT MESSAGE .TXT=MICRO.TXT/REM 
To delete files, use the following syntax: 
MFT> delete file[/options] 
where: 
delete file The name of the file to be deleted. 
/options /DE indicates the file is to be deleted. 
/REM indicates the file is on the Micro/RSX system 
remote to the host’ system. The absence of /REM 
indicates the file is on the host system. 


You cannot specify wildcards when using MFT to delete files. 


A sample file transfer session follows: 


b SET HOGS TAUTVE: TEs RET 
>A TN 
“ACCOUNT QR NAMES weer 


SFASSWORT reegwuarcd 


v 


> MET 
MF T> MESSAGE. TXT=MICRO.TXT/REM 


ZUTE-S-MFTINTITs File oreration initiated 
ZLTE-S-MFTCOMF,s File areration comelete 


RET, 
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(The cursor will be at the beginning of the last message. 
continue the operation, press RETURN.) 


MFT 


“LOGQUT 


KUTE-S-EMUFXTT> Emulation exitinses. Flease wait 
$ 


In order to use MFT, you must be using the DTE task, because 
protocol used for the file operations is unique to the two tasks. 


9.3.2 DCL Command Syntax 


If the host system is a Micro/RSX system, you use the following 
command syntax to perform file operations: 


COPY from _file[/option] to file[/option] 
DELETE file[/option] 


where: 


To 


the 


DCL 


from_file The name of the input file that MFT is to transfer. 


to file The name of the output file to which MFT is to 
the input file (from_file). 


/option /REM (remote) is used to indicate that the file 


COpy 


is 


on the local Micro/RSX system that is remote to the 
host system. The absence of /REM indicates the file 


is on the host system. 
file The file name of the file to be deleted. 
NOTE 


For input files, /REMOTE indicates that the file 
resides on the DTE system. For output files, /REMOTE 
indicates that the output file should be created on 
the DTE system. When using the DELETE/REMOTE command, 
the file to be deleted should be deleted on the DTE 
system. 
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9.3.3 Examples 


Following are examples of file operations using the DTE and MFT 
programs. 


& COPY TNFILE. TAT OUTFITLE.DAT/REMOTE 
This example copies the file INFILE.DAT from the host (MFT) system 
into OUTFILE.DAT on the remote (DTE) system. 

€¢ COPY THFTLE.GAT/REMOTE OUTFTLE UAT 
This example copies the file INFILE.DAT from the remote (DTE) system 
into OUTFILE.DAT on the host (MFT) system. 


$ TELETE FILE. OAT/RE MOTE 


This example deletes the file FILE.DAT on the remote (DTE) system. 


9.4 MESSAGES 


The following sections list and describe the messages produced by DTE 
and MFT. 


9.4.1 DTE MESSAGES 


The following messages are produced by DtTE. Some messages also 
include a 6-character octal field enclosed in parentheses. This field 
provides additional internal information regarding the cause of the 
error, but is generally not useful to you unless the information is 
also mentioned in the message description. 


?DTE-F-DEVTYPE, Illegal device type for DTE 


DTE assigned the specified emulation device and found that it was 
not a terminal. DTE can be used only on terminal devices. 


%DTE-S-DFO3SEQ, Dialing... Please hold 


The DTE /DIAL option has been specified, and DTE is attempting to 
establish a connection using a DFO3 modem (which is assumed 


present on the specified emulation terminal line). Your terminal 
is locked out until the DFO3 responds with either success or 
failure. 


?DTE-F-DFO3TMO, Telephone connection failure due to timeout 


DTE sent the dial sequence specified by the /DIAL option, and the 
DFO3 modem (which was assumed to be present) did not respond 
within 40 seconds. DTE will attempt to hang up the line and then 
exit in error. 


%DTE-S-DIALHNG, Dialup line hung up 
DTE is attempting to hang up the specified emulation terminal 


that is connected to a DFO3 modem. It may or may not have 
succeeded in hanging up. 


TERMINAL EMULATION AND FILE OPERATIONS WITH OTHER SYSTEMS 


$DTE-I-DTETVER, Data Terminal Emulator Version x.y [dd-mmm-yy] 


DTE displays its version number if the /IDENTIFICATION option was 
selected on the command line.’ 


$DTE-S-EMUEXIT, Emulation exiting... Please wait 


A CTRL/P was typed on your terminal, and DTE has begun exit 
processing. Your terminal is locked out, all DTE I/O processing 
is being completed, and all device characteristics are being 
restored. This operation takes approximately 5 seconds. 


?DTE-F-ERDDCMP, Transmission [DDCMP] failure (xxxxxx) 


During DTE/MFT file transfer, a DDCMP error occurred that could 
not be corrected after several retries. The physical (emulation) 
terminal lines are producing too many errors for a file operation 
to be performed. Usual causes for this behavior are baud rates 
that are too high, systems that are too far apart (physical cable 
length must be considered), a lack of the required terminal 
support, or some form of electrical interference (noise) along 
the physical connection (because of a bad telephone connection, 
heavy electrical equipment, and so forth). 


?DTE-F-FATALER, Internal error (xxxxxx) 
DTE/MFT has encountered an unexpected internal condition. This 
message indicates a bug in the local file operations server 
within the DTE task. 

S*DTE-S-MFTCOMP, File operation complete 
A DTE/MFT file operation has completed, and control has_ been 
returned to your terminal. If the operation has completed in 
failure, then this message will be preceded by an error message 
showing the cause of the file operation failure. 


$DTE-S-MFTINIT, File operation initiated 


DTE has received the handshake sequence from the MFT task on the 


other system. DTE invokes the file transfer server to provide 
local support for the operation being initiated on the remote 
system. Your terminal is locked out until the operation 
completes. 


?DTE-F-MSGFORM, Message format error (xxxxxx) 


The version of the MFT file server within the DTE task is not 
compatible with the version of the MFT task on the remote system. 
This may be caused by an error in the remote MFT task, or by an 
incompatibility of releases of DTE and MFT. 


?DTE~F-NOTSELD, Terminal line not selected 


This is an internal error, and indicates that the LUN has’ been 
lost. 


%DTE-S-PHONEOK, Telephone connection established 


DTE sent the dial sequence specified by the /DIAL option, and the 
DFO3 modem responded with success (it returned the character 
"A"). The connection to the remote system has been successfully 
established. 
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?DTE-F-PHONERR, Failure to establish telephone connection 


DTE sent the dial sequence specified by the /DIAL option, and the 
DFO3 modem did not respond with success. DTE will hang up the 
line and then exit in error. 


?DTE-F-PORTSEL, Assignment failure on specified device 


DTE attempted to assign and attach the specified emulation 
terminal device, and was not able to. The device may be attached 
by another user, or may be an inappropriate device type for 
emulation. 


?DTE-F-REJOPER, Operation rejected (xxxxxx) 
The file operations server within the DTE task cannot perform the 
operation requested by the MFT task executing on the remote 
system. Either the DTE task lacks the required support, or the 
version of the remote MFT task does not match the version of DTE 
being used on the local system. 

?DTE-F-RMSRERR, Remote RMS-11 error (xxxxxx) 
An error occurred during the attempt to perform the file 
operation. The RMS-11 error code (in octal) is displayed within 
the paired parentheses. 

?DTE-F-SYNLOST, Synchronization lost (xxxxxx) 


Synchronization has been lost between the local DTE and _ the 


remote MFT tasks. This may be related to the baud rate of the 
emulation terminal lines or the systems’ loads. Retry the 
operation. 


?DTE-F-SYNXERR, Syntax error 


The syntax of the DTE command either was not appropriate or did 
not fit the documented syntax. Correct the command and try 
again. 


?DTE-F-UNSPROT, Unsupported protocol operation (xxxxxx) 


The version of DDCMP being used by the local DTE file operations 
server and the remote MFT task are not compatible. The versions 
of DTE and MFT are not compatible, and the requested operation 
cannot be performed. 


9.4.2 MFT MESSAGES 


The following messages are produced by MFT. Some messages also 
include a "..." field. This indicates that all or part of the command 
line will be displayed with the message. 


?MFT-F-BADOPER, Illegal option specified: 


A nonexistent or illegal option was specified on the command 
line, or the option(s) selected is out of context. 


?MFT-F-COMFILE, Unable to open specified command file 


MFT was unable to access the specified command file. No details 
as to the reason for the failure are available. Typical reasons 
for this message are file not found, protection violations, and 
so on. 


TERMINAL EMULATION AND FILE OPERATIONS WITH OTHER SYSTEMS 


?MFT-F-FOPFAIL, File operation failed 


The particular file operation specified could not be performed. 
There are many possible causes for the failure. Typically, this 
message is produced when MFT is unable to synchronize with the 
file operations server it requests DTE to invoke. Other possible 
causes include baud rates that are too high, systems that are too 
far apart (physical cable length must be considered), a lack of 
the required terminal support, or some form of electrical 
interference (noise) along the physical connection (because of a 
bad telephone connection, heavy electrical equipment, and_ so 
forth). 


?MFT-F--ILLNODE, Illegal node combination: ... 


The MFT command string specifies both file specifications on the 
same system. Either /REM appears on both file specifications or 
does not appear on either specification. This is illegal, 
because each file specification must specify a different system. 


?MFT-F-LINELEN, Command line too long 
The command line specified was too long for the command buffer. 


Because some of the command may have been lost, the entire 
command is considered invalid. 


?MFT-F-SPECERR, Error in file specification: ... 


One or both of the file specifications supplied are in error. 
File specification syntax is limited to the standard RSX-11 
format, which is "device:[uic]filename.type;version". 


?MFT-F-SYNXERR, Syntax error: ... 
The syntax of the command line specified is in error. Possible 


causes may be illegal options, missing input or output file 
specifications, or an error in the file specification syntax. 


CHAPTER 10 


VIRTUAL MONITOR CONSOLE ROUTINE (VMR) 


This chapter begins with a brief introduction to the Virtual Monitor 
Console Routine (VMR) and continues with the following sections: 


e@ Starting VMR 

e VMR Command Syntax 

@ VMR File Specifications 

@ VMR Command Descriptions 

@ VMR Error Messages 
If you are familiar with VMR, you may want to skip directly to Section 
10.5, which is called VMR Command Descriptions. Section 10.5 contains 


command definitions, a list of parameters and keywords you can use for 
each command, and examples of the commands. 


10.1 INTRODUCTION TO VMR 


VMR is a privileged system task that allows you to configure an 
RSX-11M or RSX-11M-PLUS system image file. 


VMR commands are a subset of Monitor Console Routine (MCR) commands. 
VMR commands differ from MCR commands in that VMR commands are 
directed to the disk image of a system rather than to the current 
running system. The system image file that you configure by using VMR 
commands can later be bootstrapped. 


There are three types of VMR commands: initialization, informational, 
and task control. Table 10-1 contains a list of VMR commands grouped 
according to the function they perform. 


See Section 10.5 for a description of each VMR command. 


10.2 STARTING VMR 
You can use three methods to start VMR. These methods are described 
in the following sections. Before you start VMR, however, you must 
first assign SY: and LB: to the device that holds the system image 
file you want to modify. The symbol definition file that corresponds 
to the system image file must meet the following requirements: 

e It must have the same file name as the system image file 


@ It must have a file type of .STB 
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e It must reside on the same device and in the same directory as 
the system image file 


The symbol definition file is not necessary if you use the /IM switch. 
(See Section 10.4 for a description of the /IM switch.) 


Once you have corresponding system image and symbol definition files, 
you can start VMR. The methods for starting VMR are described in the 
following sections. 


Table 10-1 
Functional List of VMR Commands 


Type of Command Command Name 


Initialization Commands ASSIGN 
CONFIGURATION 
INSTALL 
LOAD 
REDIRECT 
SAVE 
SET 
TIME 
UNLOAD 


Task Control Commands ALTER 
CANCEL 
FIX-IN-MEMORY 
REASSIGN 
REMOVE 
RUN 
UNFIX 


Informational Commands DEVICES 
LUNS 
PARTITIONS 
TASKLIST 


10.2.1 Method 1: Running VMR 
To run VMR, enter one of the following command lines: 
PUM UME 
or 
TAME 


VMR responds by requesting the name of the system image file 
you want to modify: 


Enter filename? 
Once you enter the name of the system image file, VMR opens and 
reads the symbol definition file. Then, VMR opens the system 


image file and verifies that the file is actually a system 
image. 


10-2 


VIRTUAL MONITOR CONSOLE ROUTINE (VMR) 


Next, VMR displays the following prompt: 
YMR > 
Enter any VMR command, or exit from VMR by pressing CTRL/Z. 


On RSX-11M-PLUS systems, if the system image file you specify 
has Executive data space support, VMR scatman the spend 
messages before issuing the Pepneee 


Loeding Ex (ecutive data srace 
Data space loading comeleted 


10.2.2 Method 2: Installing and Running VMR from LB: 
To install and run VMR, enter the following command: 
SRUN €0MR 


The system installs VMR from the pseudo device LB: under the 
system directory or library directory, and then loads it. On 
RSX-11M systems, the system directory is usually [1,50] for 
unmapped systems and [1,54] for mapped systems. On 
RSX-11M-PLUS systems, the library directory is usually [3,54]. 


Next, VMR responds by requesting the name of the system image 
file you want to modify: 


Enter filename? 


Once you enter the name of the system image file, VMR opens and 
reads the symbol definition file. Then, VMR opens the system 
image file and verifies that the file is actually a system 
image. 


Next, VMR displays the following prompt: 
UM 
Enter any VMR command, or exit from VMR by pressing CTRL/Z. 
On RSX-11M-PLUS systems, if the system image file you specify 
has Executive data space support, VMR sedges the eos 


Messages before issuing the prompt: 


Loading Executive ak SPace _ 
flats seace loadine comeleted 


10.2.3 Method 3: Running VMR While Specifying an Indirect Command File 


To run VMR while specifying an indirect command file, type VMR 
followed by a_ space, then enter an at sign (@) followed by the 
name of the indirect command file. The first line of the 
indirect command file must contain the name of the system image 
file you want to modify. For example: 


“YMR @TASKS.CMN 


The system loads VMR, and then, VMR executes the indirect command 
file. VMR then exits. 
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Once you have started VMR, you can execute an indirect command 
file any time VMR prompts for input. Indirect command files are 
useful when you want to repeat a series of commands for. several 
different systems (INSTALL commands for example). 


To execute an indirect command file in VMR, enter an at sign (@) 
followed by the name of the indirect command file any time that 
VMR prompts for input. For example: 


YMRS OTASKS. CME 


VMR executes the indirect command file, extracting command input 
from the specified file until it reaches the end of the file and 
then returns to the terminal for further input. 


VMR supports two levels of indirect command files. This means 
you can invoke a_ second indirect command file from within the 
first indirect command file. However, if you try to invoke a 
third indirect command file from within the second indirect 
command file, you receive an error message. 


10.3 VMR COMMAND SYNTAX 


The following sections describe how to format VMR commands and how to 
enter comments in VMR command lines. 


10.3.1 VMR Command Format 


VMR command lines can contain a command name, parameter, keyword(s) 
and keyword value(s). The components of a VMR command line are 
described as follows: 


Command Name 
The name of the VMR command. 
You can abbreviate all VMR command names to 3. characters. 
VMR accepts 3 characters and then searches for a space or 
tab followed by the command parameter or by a RETURN if 
there are no parameters. Note that VMR does not permit 
embedded spaces or tabs in command names. 
Parameter 
The parameter for the command. 
Certain VMR commands require parameters. VMR parameters can 
“be file specifications, keywords, devices, or task names. 
You must always precede a parameter with a space or tab. 
Keyword 
One or more keywords for the command. 
VMR keywords are command specific. Most VMR keywords are 


preceded by a slash (/). Some VMR commands permit more than 
one Keyword per command line. 
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VMR keywords can be placed in any order in a command line 
and still have the same meaning. For example, the command: 
YRRSTHS TEST. TSK /TASK=SUPER/PMNEYES 
has the same meaning as: 
YMRS INS TEST. TSR/PMGSYES/TASK=SUPER 
Keyword Value 
The value for the keyword. 
You must always precede a keyword value with an equal sign 
(=) or colon (:). In the following command line, =SUPER is 
the keyword value assigned to the keyword /TASK. 


VARS ING TEST. TSK/TASK=SUPER 


10.3.2 Including Comments in VMR Commands 


VMR interprets an entire line of text as a comment if the first 
character in the line is a semicolon (;). For example: 


WME 5 THIS LINE 15 A COMMENT 
To insert a comment within a command line, use an exclamation point 
(!) at the start of the comment, and an exclamation point or RETURN at 
the end of the comment. VMR ignores all text between the two 
exclamation points or between the exclamation point and the RETURN. 
For example: 

YMRETAS 'THIS TS A COMMENT STRING @ér 


Comments are especially useful to clarify command lines in VMR 
indirect command files. 


10.4 VMR FILE SPECIFICATIONS 
VMR accepts the standard RSX-11M/M-PLUS file specification format: 
ddnn:[{directory]filename.type;ver[/IM] 
The components of VMR file specifications are described as follows: 
ddnn: 
The name of the device on which the file is located. 
A device name consists of two ASCII characters (dd), 
followed by an optional 1- to 3-digit octal unit number 
(nn). You must include a colon (:) at the end of the device 
name. For example: 


DM1: 


The default device in VMR is SYO:. 
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[directory] 


The directory in which the file is located. 


There are two types of directories in VMR, numeric and 
named. A numeric directory contains two octal numbers, from 
1 to 377, separated by a comma and enclosed in square 
brackets ([ ]). For example: 


(1,54) ' 
Named directories are valid on RSX-11M-PLUS systems only. A 
named directory consists of 1 to 9 alphanumeric characters, 
enclosed in square brackets ([ ]). For example: 

[1Gcy] | 


If you do not specify a directory, the system defaults to 
the directory under which VMR is currently running. 


filename 


type 


ver 


The name of the file. 


In VMR, a file name can consist of up to 9 alphanumeric 
characters. For example: 


RSX11M 


There is no default file name in VMR. 


The type of file. 


VMR file types can consist of 1 to 3 alphanumeric 
characters. You must precede a file type with a period (.). 
For example: 


-SYS 
File types are optional. However, omitting a file type may 


cause VMR to assign one by default. VMR assigns default 
file types to the following files: 


System Image File .SYS 
Task Image File -TSK 
Indirect Command File -CMD 


The version number of the file. 


A version number helps differentiate files that would 


otherwise have identical file specifications. Always 
precede a version number with a semicolon (;). For example: 
72 


On RSX-11M systems, the version number is a number from 0 to 
77777(octal). On RSX-11M-PLUS systems, if you select 
support for decimal version numbers during system 
generation, the version number is a number from 1 to 
32767 (decimal). 
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If you do not specify a version number for a file, the 
system defaults to the highest version number of that file 
in the directory. 
/IM 

A switch that, when added to the specification for the 
system image file, overrides the VMR requirement for the 
symbol definition file. If you use the /IM switch when you 
specify a system image file, the only command VMR accepts is 
the SAVE command. 

You use the /IM switch to write non-RSX-11M/M-PLUS system 
images to secondary media in bootable format. The /IM 
switch is also useful when you use an RSX-11M/M-PLUS' system 
as a host system for developing small, memory-resident 


systems that must be loaded from a serial medium, such as 
paper tape. 


10.5 VMR COMMAND DESCRIPTIONS 

The following pages include descriptions of the VMR commands in 

alphabetical order. Each command description contains the following 

information: 

Command Abbreviation 

The minimum number of letters that you must specify when 
using the command name. The command abbreviation is located 
at the outside margin of each page in capital letters. 


Command Name 


The full command name in capital letters. The command name 
is followed by text describing the command's function. 


Format 
The format(s) you should use when specifying the command. 
Parameters 
The command's parameters. 
Keywords 
The command's keywords. 
Examples 
Examples of command use and output. 
Notes 


Additional information about the command. 
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ALT 


ALTER 


Use the ALTER command to change the static priority of an installed 
task. 


Format 

ALTCLER] taskname /PRI=priority 
Parameters 
taskname 


The name of the task whose priority you want to alter. 


/PRI 
The keyword that changes the task's static priority. 

priority 
The new priority, from 1 to 250, you want to assign to the 
specified task. 
250 is the highest priority and 1 is the lowest priority you can 
assign. Therefore, a task with a priority of 200 takes 
precedence over a task with a priority of 199. 
The priority you enter is assumed to be octal unless you place a 
period (.) after the priority number. 

Example 


VNR ALT TEST /SPRTZ2 40. 


Alters the static priority of task TEST to 248(decimal). 
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ASN 


ASSIGN 

Use the ASSIGN command to define, delete, or display logical device 
assignments. Logical device assignments are a way to associate 
logical names with physical, pseudo, or logical devices. When you 


assign a logical name to a pseudo or logical device, the system 
resolves the assignment to the associated physical device. 


There are several types of logical-device assignments. VMR_ supports 
the manipulation of global assignments only. Global assignments apply 
to all tasks in the running system. 
oe : | 

On RSX-11M-PLUS systems with extended logical name 

support, the VMR ASSIGN command cannot be used to 

Manipulate logical names of any form other than linn:. 
A logical device name has the same syntax as that of a physical device 
unit. It consists of a 2-character ASCII name (alphabetic) and an 
optional l- or 2-digit octal unit number, followed by a colon (:). 
The 2-character name can be either equivalent to a= standard 
RSX-11M/M-PLUS device name (for example, DK:) or formed by two letters 
picked at random (for example, 2Z22Z:). If a logical device name is 
identical to a physical device name, the logical name is the one’ used 
by the system. 
The ASSIGN command has three formats. These are described as follows: 
Format 1 

ASN ppnn:=llnn:/keyword 


Defines a global assignment that associates the logical name linn: 
with the device ppnn:. 


Format 2 

ASN /keyword 
Displays all global assignments for the system. 
Format 3 

ASN =[1llinn:]/keyword 


Deletes the specified global assignment, or, if you omit 1inn:, 
deletes all global assignments. 


Parameters 
Ppp 
A physical, logical, or pseudo device name. 


nn 


A unit number. 
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ASN (Cont.) 


1: 


A logical device name. 


/keywords 


One 


Keywords 


/GBL 


of the following: 


/GBL 


/ SYSTEM 


Defines, displays or deletes global logical device assignments. 


Examples 


l. 


- (RSX-11 


VNROASN TMD SOKO? (GEL. 


Defines the global logical device name GBO: and assigns it 
to DM:. 


VMREASN /GBL 
oe 


‘support for extended 
figumente, 


logical 1 
VMESASH =/GBL. 


Deletes all global assignments. 
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CAN 


CANCEL 
Use the CANCEL command to cancel time-based initiation requests for a 
task. These requests result from the RUNS directive or any of the 
time-synchronized variations of the VMR RUN command. 
The CANCEL command does not affect the execution of a task active in 
the saved system image. The CANCEL command removes only the 
time-based schedule requests still in the queue. 
Format 

CAN[CEL] taskname 


Parameter 


taskname 


The name of the task whose time-based initiation requests are to 
be canceled. 


Example 
YMRS CAN MEE 


Cancels all periodic rescheduling and time-based initiation 
requests for task XKE. 
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CON 


CONFIGURATION 


bos command to set the 
(CSE xr address of a budge _to 
display system configuration information, = 


The CONFIGURATION ‘command has two den oee These are ‘described as 
follows: 


Format 1 
CoNLFIGURATION] SET ‘controller-name CSRevalue 
Or 


CONT PIGURATION] SET controller-name VEC=value 


Sets the CSR or vector address of a “device. : You can enter pay one 


value per command line. 2 


Parameters 
controller-name 


The name of the controlle ‘fo Ww ch e@ CSR or vector address is 


to be changater 
CSR=value , ean 
The new CSR address for t e 
VEC=value : a 


The new vector address fo 


Format 2 


CON[ FIGURATION] bistPLav] 


Displays system configuration information on your terminal. 
Parameters Py es a 
keyword 
One of the following: 

CONTROLLERS] 

UNI[TS] 

cpu 

FUL[L] | 


FOR string 


A parameter that restri s the display to the devices matching 
the specified Btring. 0 eee is 
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) Cont 


m. The UNITS 


device on that 
nformation is 


controller to 340. 
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CON (Cont.) 


Single-Processor Systems 


3. 


VER CONF IGUR 


DEO! 


DBL: 
TB? 3 
DE: 


a) 


NLOY 


VTO3 


RDO: 


VMRS 


VARS 


UHR? CON ps. 


CFA 

RHA 
aa 
RHC 
RHN 


a 


DEO 3 


Rit 


B2¢ 


VMRDCON DIS 
CRA 


: RHAD! 
DR3i 
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LAY. CONTROLLERS , | 

— (SR=176700 - yenezsa PRI=S 
CSR= =176300 VEC-=180 FRI=5 
CSR=172040 VEC#204 PRI=5 
CSR=172440 © VEC2?24 PRI=S 


YMA OFL —sCFA——SCOCSR#I70500 = VEC =300 PRI=5 
ZA. 


as  {SR=140100  —- VEC=340 PRIB5 
VER? SE ESB AR ks: GEES BB Sie : i S ; s 


at ae  BRIVER | 
a Q 2 na DRIVER 


 VECS2S4 PRI=§ 
YER EL5S0 PRIRS 
| NECE?O4 PRT=5 
(6 | VE@S2BAFRIZ5 


OFL 
OFL 
OF L. 


OFL ss RIVER 
ODPL a ORTVER © 

OF 9 DRIVER. 
OFL TRTVER - 


RHAOt 


er 


OFL: DRIVER 
OFL TRIVER 
ONL ss DRIVER © 
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DEV 


DEVICES 


Use the DEVICES command to display the symbolic names of all device 
units in the system image of a particular device type. If you do not 
specify a device type, VMR displays the symbolic names of all device 
units. 


The device names appear in a single vertical column. A second column, 
to the right, contains additional information about a device (see 
Notes). 


Format 

DEV[ICES] [dd:] 
Parameter 
dd: 

The device type. 
Example 


VME OTE Y 

LFO? Loaded 

NEO? Loaded 

ORL Loaded 

Nuet Loaded 

NTO? Losded 

Loevwed 
loated 

Loaded 

Loarect 

Loaced 

Loaecec 

Loaded 

Lgantead 

Loaded 

UM? fnoaced 

UM? $ Loaded, 

QRGt Loaded 

VRE? Loaded 

NSO OF fline Loaded 

MG? Offline Leeder 

UTO? Loartec 

NWT1) Loaded 

QNXG? Loaded 

MMI? Loeded 

ERA? Uri lo aseted 

HO Leader 

M44¢o loiseced 

PD ¢ TTSG: 

TTGO? based 

iT1?) Loaded 

TTSt Loaded 

TTRS Loaded 

TT43 Loscded 
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DEV (Cont.) 


The pseudo device SY: is not redirected to the bootstrapped 
device until the system is bootstrapped. 


The following list describes the types of messages that can 
appear in the second column of the device list when you use 
the DEVICES command. (More than one message can appear on 
the same line.) 


@ LOADED indicates that the driver for the device is 
loadable and currently loaded. 


@ UNLOADED indicates that the driver for the device is 
loadable but not loaded. 


@e The absence of either LOADED or UNLOADED in the second 
column indicates that the driver is permanently resident. 
This means the driver is part of the Executive. 


-11M systems, that although the 
entry for the device, the device 
to the system. 


e OFFLINE indicates, 
device list con 
is not currently 


M-PLUS, that a device has yet 
, reconfiguration task. All 
e list have this notation in 


to be brought — 
physical devices 


e A device name in the second column is the device to which 
the corresponding device in the first column has been 
redirected. 
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FIX 


FIX-IN-MEMORY 


Use the FIX command to load a task into memory and, on RSX-11M-PLUS 
systems, to load a region into its partition in the system image. VMR 
can fix a task in the system image only if the partition in which it 
is to be fixed is available. 


Fixed tasks remain in memory even after they exit. Therefore, the 
system can run a fixed task faster because the task is memory-resident 
and does not need to be reloaded. Reexecuting fixed tasks however, is 
not always practical. If you expect to reexecute a fixed task, you 
should write it in such a way that it initializes all impure data and 
LUN assignments at run time. 
The following restrictions apply to the fixing of tasks: 

e@e You must install a task before you fix it. 

@e Active tasks cannot be fixed. 


@ On RSX-11M systems, you cannot fix checkpointable tasks. 


@ On RSX-11M-PLUS systems, do not fix a checkpointable task 
because fixing a checkpointable task makes the task. 


noncheckpointable. 

@ On RSX-11M-PLUS systems, you cannot fix tasks whose names are 
in the forms ...xxx and xxx$$$ because that copy of the task 
is never executed. (The task is a prototype task.) 


@e On RSX-11S systems, all installed tasks must be fixed because 
they cannot be loaded into the running RSX-11S system. If the 
RSX-11S system has memory management (PLAS) support, you 
cannot use the FIX command to fix tasks. You must use the 
INSTALL /FIX command instead. See the description of the 
INSTALL /FIX command. 


@ On RSX-11M and RSX-11S systems, you can fix tasks above’ the 
124K-word limit. Before you fix a task above the 124K-word 
limit, however, you must first create another copy of the 
system image file larger than 498(decimal) blocks. The system 
image file you create must be larger than 498 blocks because 
the size of the system image file created during system 
generation is 498 blocks for a system of 124K-words. 


Use either the UNFIX or REMOVE command to remove a fixed task from 
memory or remove a region from its partition. 


Format 
FIX taskname[ /keyword] 
Parameter 
taskname 
The task or region that you want to fix in memory. If you do not 


specify a keyword, VMR assumes that the task is a single-user 
task. 
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FIX (Cont.) 


/keyword (RSX-11M-PLUS systems only) 


/NSF 


/REG 


/RON 


One of the following: 


Specifies that the task to be fixed is a directive common. 
Directive commons are used to hold some of the Executive 
directives instead of keeping them in Executive address’ space. 
Because directive commons contain Executive code, they must be 
installed and fixed in the system image before the system can be 
boot strapped. Directive commons are installed and fixed in the 
system image by commands in ailatlions CMD — as part of the system 
generation procedure. 


Individual directive commons are installed and fixed contiguously 
in memory to form one large _ directive common called DIR1IM. 
DIR11M must be fixed in memory before any other directive commons 
can be fixed. Other directive commons must be fixed contiguously 
to DIRIIM. Hee i a Fo 


Directive commons cannot be shuffled, which means means that the 
Shuffler cannot move them around in memory after they have been 
fixed. For more information about the Shuffler, see Chapter 14. 


To eliminate a directive common, use the REMOVE command. 


Specifies that a fixed task cannot be shuffled. This means that 
the Shuffler cannot move the task around in memory after the task 
has been fixed. For information about the Shuffler, see Chapter 
14. 


Specifies that the task to be fixed is a common region. 


| speci Hes that the task to be fixed is a multiuser task and that 


the read-only portion is to be fixed in memory. 


You must specify the entire task name. 


Examples 


Let SHE SP I REE 


Fixes the task XKE in its partition. 


10-19 


VIRTUAL MONITOR CONSOLE ROUTINE (VMR) 
FIX (Cont.) 


2. VERSE TICOM/REG/NSE 


Fixes the cesident, Gomeee TTCOM in its. “partition, and 


eneci tien that the task cannot be shuffled. 
3. VHR> FIX. + oETT/RON | 


Indicates that the. EDI aalear is bane as eo multiuser task 
and fixes the task’ Ss read-only portion in memory. | : 
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INS 


INSTALL 
Use the INSTALL command to make a_task or common recognizable to the 
system. On RSX-11M and RSX-11S systems, you can also use the INSTALL 
command to load a common into a common partition. See the description 
of the FIX command for more information. You can install commons 
above the 124K-word limit. You cannot run a task until you install 
it. 
Once a task is installed, VMR creates a Task Control Block (TCB) for 
the task in a system image table called the System Task Directory 
(STD). The task parameters contained in the TCB enable the system to 
run the task when requested to do so by an MCR command, VMR command, 
or a system directive. 
Format 

INS[TALL] filespec[ /keyword(s)] 
Parameters 
filespec 

A task image file specification in the form: 


LB:£g,m]filename.type; version 


The task image file you specify must be on the device LB:. The 
file type defaults to .TSK. 


/keyword(s) 
Any keyword you specify either provides parameters that were not 
specified at task-build time or overrides parameters that were 


specified at task-build time. 


One or more of the following: 


/CKP=option 

/CLI=option 

/FIX=option 

/FMAP=option 

/INC=size 

/IOP=option 

/PAR=pname 

/PMD=option 

/PRI=number 

-/PRO=[ system, owner , group,world] 


/RON=option 
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INS (Cont.) 


/ROPAR=pname 
/SEC=option 
/SLV=option 
/SYNC=option 
/TASK=taskname 
/UIc=[group,me 
/WB=option 
/XHR=option 
Keywords 
/AFF=[URM(s) ] 
(RSX-L!M-PLUS mu. 
(URM) affinity 
Enclose. the URM(<: 


If you specify mo 
commas . For exar. 


/seP=CUBE, Ur 


When you specify 
on the processor 


UNIBUS- run-mask 


mber ] 


tiprocessor systems only.) The UNI 
of the task. You must specify at 
) in square brackets (f£ J). 

re than one URM, you mus? sepa 
ple: ‘ 

F,UBH] 

the /A?F keyword, the instailed ta 
to which the specified URMs are co 


The three-letter name of the URM for the CPU 
UNIBUS Pvt: The following name 5 are 
specificaticns: 

CPA UBE UBK UBP 

CPB UBF UBL UBR 

CPC 1iBR UBM UBS 

CPD UBJ UBN UBT 

/CKP=option 
(For systems that support dynamic allocation 


BUS Run Mask 
Teast one URM. 
rate them by 
se runs only 
neected. 


switched 
alid URM 


Or 


of checkpoint 


space.) Enables or disables checkpointing for a task. 


The options are 
enabled 
the task. 


The task image file need not contain allocated checkpoint 


The 


On RSX-11M systems, 


YES 
for the task. 


and NO. If /CKP=YES, che 
If /CKP=NO, checkpointing i 


from a checkpoin 


/CKP keyword is disabled for that task. 
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t file. 
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INS (Cont.) 


The /CKP keyword overrides the /CP switch specified at task-build 
time. 


The default is /CKP=YES. 
/CLI=option 


Indicates that the task being installed is or is not a command 
line interpreter (CLI). 


The options are YES and NO. /CLI=YES indicates that the task is 
a command line interpreter. /CLI=NO indicates that the task is 
not a command line interpreter. 


You must indicate that a task is a CLI, either by installing it 
with the /CLI=YES keyword, or by taskbuilding it with the /CL 
switch, before you can set a terminal to that CLI or work with 
the CLI by means of the MCR CLI command. See the RSX-11M/M-PLUS 
and Micro/RSX Task Builder Manual for more information on the 


SS Ooo soo as 


The default is whatever was specified at task-build time. 
/FIX=option 

(RSX-11S systems only.) Indicates whether tasks on RSX-11S 

systems with memory management (PLAS) support will be fixed in 


memory. 


The options are YES and NO. When you specify /FIX=YES, the task 
is installed and fixed in memory. 


On RSX-11S systems with memory management support (PLAS), VMR 
requires that you fix all tasks by using /FIX=YES. You cannot 
install the task and fix it later with the FIX command. 
The default is /FIX=NO 
hee teen : | 
— (RSX-1IN-PL DS ayacens ony. yo Anforus oe aeten that the task 


will use the fast-mapping feature of the Executive. You can use 
the /FMAP keyword Bry with tasks that have external Readers « 


he” options. are YES and NO. /PMAP=YES indicates the task will 
use the _fast-mapping > feature — of the Executive. /FMAP=NO 
icates. the Seen will et pee ne oe lene oa oe 


See the deucviptice oe the XHR- a oe more daiormetion 

bout external headers and the RSX-11M/M-PLUS and Micro/RSX 

Bees Reference Manual» for. more information “a about fast 
| SARE aS «| oS 


‘The default is whatever was apecd €ted at ‘Gaek-bulla time. 
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/INC=size 


(Mapped systems only.) Indicates the extension size of a _ task. 
The extension size refers to the number of additional words of 
address space you want allocated to a task running in a 
system-controlled partition. The extension size is usually 
expressed in octal but may also be expressed in decimal by 
following the size with a period (.). 


Tasks such as MAC, TKB, PIP, VFY, and AT. (Indirect) use the 
space from the end of the task image to the end of their address 
space, as dynamic memory in which to allocate symbol tables and 
buffers. The /INC keyword defines the number of words in this 
dynamic region. The /INC keyword overrides the Task Builder's 
EXTTSK or PAR options. 


If a common is installed with an increment, it will no longer fit 
in its original task image file. Therefore, you cannot specify 
both /INC=size and /WB=YES when installing a common. . 


The default size is the size specified at task-build time or zero 


(0). 
/IOP=option 


Informs the system that a privileged task needs access to the I/O 
page. 


The options are YES and NO. If /IOP=YES, INSTALL assumes’ that 
the task will use the I/O page and, if the task is larger than 
8K-words, issues a warning message because the I/O page will not 
be mapped. If /IOP=NO, INSTALL assumes that the task does not 
need to use the I/O page. No warning message is issued. 


The default is whatever was specified at task-build time. 
/PAR=pname 


Indicates a partition that overrides the partition name specified 
at task-build time. If the partition you specify does not exist, 
VMR issues a warning message and attempts to install the task in 
the GEN partition. 


On RSX-11M systems, if the task you install is built with 
checkpoint space allocated in the task image file, and you 
specify a user-controlled partition with the /PAR keyword, the 
task's allocated checkpoint space may no longer be large enough 
to hold the task. The reason for this is that when you specify a 
user-controlled partition, the size of the task is automatically 
extended to the size of the partition. If the user-controlled 
partition specified when the task is installed is larger than the 
task size specified when the task was built, the task will no 
longer fit in its allocated checkpoint space. 


The default is whatever was specified at task-build time. 
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/PMD=option 
Informs the system whether a Postmortem Dump is required. 
The options are YES and NO. If /PMD=YES, the system performs a 
Postmortem Dump of the task when the task is aborted because of 


an SST error condition. If /PMD=NO, the system does not perform 
a Postmortem Dump when the task is aborted. 


To generate a Postmortem Dump, you must install the Postmortem 
Dump task PMD... in the system. /PMD overrides the Task 
Builder's /PM switch. 


The default is whatever was specified at task-build time. 
/PRI=number 


Indicates the priority, from 1 to 250, you want assigned to the 
installed task. 


250 is the highest priority and 1 is the lowest priority you can 
assign. Therefore, a task with a priority of 200 takes 
precedence over a task with a priority of 199. 


The priority you enter is assumed to be octal unless you place a 
period (.) after the priority number. 


The default is PRI=50(decimal). 


‘/PRO=[ system, owner , grc 


Allows a ta 
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The user groups are defined as follows: 
System 


All system tasks running under a UIC group number less 
than or equal to 10(octal). 


Owner 
Tasks that run under the same UIC as the file's owner. 
Group 


Any task that is running under the same UIC group as 
the file's owner. 


World 


Any task that does not fit in one of the above 
categories. 


You assign a group unlimited access by ‘specifying RWED in the 
group's position. You assign a group no access by ifesetiyg a 
comma in the group's position. — For Reeneie: 

/PRO=[RWED, RWED, , RWED] : 


Here, a task running under the same ‘UIC grgup as the file's owner 
has no access. : : : 


You cannot specify protection: options. for a read-only common 
region or the read-only — portion of a multiuser task. A task 
linked to a common region with an Appronet protection mask cannot 
be installed. oe : 
The default is jchahs boil race ee es. 

/RON=option : 


(RSX-11M-PLUS systems only.) Informs the system that a common 
region is or is not read-only. 


The options are YES and NO. If /RON=YES, the region is installed 

as read-only. If /RON=NO, the region is installed with 

read/write access. 

The /RON keyword overrides the effect of the /PRO keyword. 

The default is /RON=NO. | 
/ROPAR=pname 

(RSX-11M~PLUS systems only.) Indicates the read-only partition 

(pname) into which the read-only portion of a multiuser task is 

to be installed. 

If the partition you specify does not exist, VMR issues a warning 

message and attempts to install the read-only portion of the task 

into the partition containing the read/write portion of the task. 

The /ROPAR keyword overrides the Task Builder options. 


The default is whatever was specified at task-build time. 
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/SEC=option 


(RSX-11M-PLUS systems only.) Places the Task Control Block (TCB) 
for the task being installed in secondary pool. 


The options are YES and NO. If /SEC=NO, the TCB for the task is 
placed in primary pool instead of secondary pool. The /SEC 
keyword is valid only for tasks whose names are in the form 
oe eXXX OYF xxxS$S$. 


The default is /SEC=YES. 
/SLV=option 
Informs the system of the task's slave status. 


The options are YES and NO. If /SLV=YES, data sent to the 
installed task is marked with the TI: of the sending task. When 
the installed task receives the data, the system sets the task's 
Jig a to that associated with the data. The /SLV=YES keyword 
overrides the Task Builder's /SL switch. If you specify /SLV=NO, 
the TI: of the task does not change when the task receives data. 


On RSX-11M-PLUS, the /SLV keyword cannot be used with tasks whose 
names are in the form ...xxx. These tasks are prototype tasks 
and cannot be installed as slaved tasks. 


The default is whatever was specified at task-build time. 
/SYNC=option 


(RSX-11M-PLUS multiprocessor systems only.) Synchronizes task use 
of a common, permitting several tasks to share a common and use 
the common for synchronization. For example, if two tasks access 
the same common, the /SYNC keyword ensures that only one of the 
tasks executes at one time. This prevents the second task from 
reading from or writing to the common while the first task is 
executing. 


The options are YES and NO. You can specify /SYNC=YES for two or 


more tasks, but only one of the tasks can execute at one time. 
If one of the tasks becomes blocked, the others compete to 
execute. 


The default is /SYNC=NO. 

/TASK=taskname 
Specifies the name you want to give the task. 
The default is the name specified at task-build time or the first 
six characters of the file name. See the RSX-11M System 
Generation and Installation Guide or the RSX-11M-PLUS System 


Generation and Installation Guide for an explanation of multiuser 
system defaults. 
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/UIC=[ group,member ] 


Specifies the UIC for the task. The task's UIC determines’ the 
file-protection class (system, owner, group, world) to which a 
task belongs. You must use square brackets ([ ]). 


You can use the /UIC keyword only when installing tasks started 
by a RUNS directive or started by a RUN command that specifies a 
time delay. You can override the UIC with the RUN’ command. 
Tasks installed with names of the form ..xxx and tasks started by 
the RUN command without a time delay run under the protection UIC 
of the terminal from which the command was issued. 


The default is the UIC specified at task-build time. 
/WB=option 


(RSX-11M-PLUS systems only.) Specifies where a read/write common 
will be checkpointed to. By default, a common is checkpointed to 
a system checkpoint file. 


The options are YES and NO. If /WB=YES, the common is 
checkpointed to its original task image file. When the common is 
removed, it is written back to its original task image file. If 
/WB=NO, the common is checkpointed to a system checkpoint file. 
The common is not written back when removed. 


If a common is read-only, there is no need to checkpoint it. 
Therefore, the /WB switch is ignored when a common is installed 
with /RON=YES. : 


If a common is installed with an increment, it will no longer fit 
in its original task image file. Therefore, you cannot specify 
both /INC=size and /WB=YES when installing a common. 


The default is /WB=NO. 
/XHR=option 


(RSX-11M-PLUS systems only.) Specifies that the Executive's copy 
of the task's header will be in an area external to the system's 
dynamic storage region (pool). 


The options are YES and NO. If /XHR=YES, the task is installed 
with an external header. If /XHR=NO, the task is installed with 
a resident header. 


When you specify /XHR=YES, the task's header is not kept in pool. 
Instead, a copy of the header is placed in a reserved area 
immediately below the task image. The Executive uses the copy of 
the header rather than the actual header. When the task is 
checkpointed, the system writes the task image and the copy of 
the header into the checkpoint file. The header in the task 
image is left unchanged. 


The /XHR keyword correlates with the /XH option for the Task 
Builder. The default for /XHR and the ability for a user to 
override the option specified at task-build time depend on how 
the INSTALL task was built during system generation. 
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You can change the effect of the /XHR keyword by selecting one of 
several options. The options determine the default action the 
system takes when a task is installed. To select an option, your 
system manager must modify INSBLD.CMD, the build command file for 
the aNSTALL task. 


INSBLD. cMD mic include the following command line: 
| a GBLPAT = INSROT:$HDDEF:/n 


where n is the carieatace of the desired option. The default option 
aaa 1. 


After the command file has been modified, the INSTALL task must 
be rebuilt and then reinstalled in the system with VMR. 


You can select one of the following options: 


1. By default, every task is installed with an external header. 
You can override this option by specifying /XHR=NO. This 
option is provided for users who want their system always to 
install tasks with external headers. The option also 
prevents users from unnecessarily or accidentally using 
headers in pool. Pe eee 


For existing RSX-11M-PLUS sites, selecting this option allows 
the use of external headers without having to rebuild the 
poles iv ieged application ayeree: 


2. By default, the headers for privileged tasks are in pool and 
the headers for nonprivileged tasks are external. This 
option can be overridden when a task is built or installed. 

This option is provided for users who have user-written 

privileged code that needs to be converted before it can 
execute with an external header. The application system does 

not have to be rebuilt to use external headers. 


3. By default, the headers for all tasks are in pool. You can 
override this option when the task is built (/XH) or when the 
task is installed (/XHR=YES). This option is provided for 
users who have user-written ACPs or privileged code that 
examines the header of another task. 


If you select this option, you must either rebuild or install 
a task with an external header (TKB /XH or INS /XHR=YES) 


before it can execute with an external header. Because any 
user can specify the /XH switch, this option is recommended 
for friendly environments. (Only privileged users can 


specify the /XHR keyword.) 


4. By default, the headers for all tasks are in pool. The 
option can be overridden by a privileged user by specifying 
/XHR=YES when the task is installed. 


This option is similar to option 3, but it cannot be 
overridden by the Task Builder's /XH switch. The option 
gives the system manager more control over the environment 
and must be selected for those systems that cannot allow any 
code, including nent ie Lheged code, to execute with external 
headers. 
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5. By default, the headers for all tasks are ir pool. This 
option cannot be overridden. Selecting this option is not 
recommended. The effect of the option is similar to choosing 
a nonstandard Executive during system generation, so that 
support for external headers is not included. This option 
must be selected, however, for those systems that cannot 
allow any code, including nonprivileged code, to execute with 
external headers. 


Note that the options do not apply to tasks that were built with 
the /-XH switch specified. The headers for these tasks are 
always in pool when the tasks are installed, regardless of the 
option selected, because the /XHR keyword cannot override the 
/~XH switch. 


Examples 
1d. UME SrRSTADL <mar 
Installs task SCAN using the default priority and directory. 
2. VAR TNS SM AN LT oVRS 
Informs the system that the task SCAN is a CLI. 
3s MEP tae. EAR Me TY eves 


Requests the system to install SCAN and fix SCAN in memory. 
4.0 VERS TNS SCAN SF MAPS YES 


Informs the system that the task SCAN will use the 
fast-mapping feature of the Executive. 


5. U4 THE Stade TOP YES 
Informs the system that the privileged task, SCAN, needs 
access to the I/O page. 

6. UMS ba Pare (ale ANS PAR SEY arr 


Installs task MAC in the partition SYSCTL and increases’ the 
task size by 4096(decimal)-words. 


7. WARDENS TALL ML ECL LLLISO AN, TSE E4/PRE 18 
Installs task SCAN, file type .TSK, version 4, from device 
DMl:, group number 1, member number 111, with a priority of 
103(octal). 

8. YAR STMS SEAN/ZE Roe De RUE Ty ss] 
Requests the system to install the task SCAN with a 
protection mask that permits tasks running under the same UIC 


as the file's owner to have Read, Write, Extend, and Delete 
access. Tasks with other UIC's are denied access. 


LO 30 


10. 


Notes 
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VAR THS SMAN/SYNE=YES 


Informs the system that other tasks can share a common with 
the task SCAN but that only one of the tasks may execute at 
one time. 


VAEO INS BOOSWR& VE 


/gpecities that the read/write common BOO will be ehackpointed 


to its original task image file. 


On RSX-11M systems, changes made in a common are made only in 
the memory image of the common. Therefore a common does not 
retain changes when it is removed and then reinstalled. 


On RSX-11M-PLUS systems, changes made in the memory image of 
a common can be preserved when the common is removed by 
installing the common with the /WB=YES option. 


If the common has been installed with the /WB=YES option, the 
REMOVE command writes the common, with its changes, into its 
original task image file replacing the original image. When 
the common is reinstalled, the new version of the common (as 
it existed in memory > when ait was removed) is placed in 
memory. eee 


On RSX-11M-PLUS systema, you not use the INSTALL command 
to install device commons that have been created with the SET 
/PAR command. (A device common is a special type of common 
that occupies physical addresses in the I/O page.) 


When you use the SET conmand: to. create a device partition, 


the following operations occur: © 


1. If the device partition being created is the first device 
partition in the system, the system automatically creates 
a main partition called I0O PAR. The partition being 
created then becomes a subpartition of IO PAR. 


2. The system creates an entry for the new device partition 
in the Common Block Directory (CBD) and inserts the 
partition into the directory. The device partition is 
now a device common. 


Because the system creates a common block for the device 


partition automatically, there is no need to install it as a 


common. Attempting to do so results in an error message. 


When VMR installs a task in an unsaved system, it stores’ the 
task's Logical Block Number (LBN) in the Task Control Block 
(TCB). When you save a system, the SAVE command places’ the 
file identification, rather than the file's LBN, in the TCB. 
When the system is rebooted, it opens the task file and 
stores the task's new LBN in its TCB. If a task has been 
deleted, the system cannot open the task file when the system 
is rebootstrapped. The system then automatically removes the 
task's TCB from the System Task Directory (STD). 
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When VMR installs a task in a saved system image, it stores 
the task's file identification, rather than the LBN, in the 
TCB to allow a rebootstrap to occur’ successfully. It is 


important that a saved system image not retain the physical 
disk addresses of the installed tasks because the Disk Save 
and Compress Utility Program (DSC) or the Backup and Restore 
Utility (BRU) can compress and copy a disk containing a saved 
system, thus moving the task files to different physical 
locations. Because the TCB entries contain task file 
identifications rather than LBNs, the system can function 
normally when it is rebootstrapped. 
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LOAD 

Use the LOAD command to load a nonresident device driver into the 
system image. LOAD either links a driver to an already resident data 
base or loads a loadable data base with the driver. This command 
eliminates the need to link infrequently used device drivers 
permanently into the Executive. 


Executive support of loadable device drivers is a system generation 
option on RSX-11M but is always included on RSX-11M-PLUS. 


Format 

LOA[D] dd:[/keyword(s)] 
Parameters 
dd: 

A 2-character ASCII device name. 
/keyword(s) 

One or two of the following: 
/cTB=ccLa,b,...] 
/PAR=pname 
/SIZE=psize 
/VEC 

edocs 


is oo name. Be the 


- (Rsx-tim-pius- eysten kue 
ios hould be used instead of 


_ $aacrB in the » loadable ata base. 


a bis are lots in the cTB' s KRB table that should “point” at 
oe the KRBs in the loadable data base. 


The. slots are. named A,B, e. D,E,F, H, J, Kb; M, NLP, R,S, ae 


/ere | keyword is. used to load a driver that references plit. 
8 base. Refer to the RSX-11M-PLUS Guide to Writing an 1/0 

Driver for more information. Te 
/PAR=pname 


The partition into which the driver is to be loaded. The pname 
value is name of the partition. 


The /PAR keyword overrides the partition specified at task-build 
time. 


10-33 


VIRTUAL MONITOR CONSOLE ROUTINE (VMR) 


LOA (Cont.) 


/SIZE=psize 


The minimum size of the partition (psize) in octal-words into 
which the driver is to be loaded. 


VMR rounds the partition size up to the next largest unit of 
100(octal). The partition size must be less then 7774l(octal). 


/VEC 
(RSX-11M-PLUS systems only.) Informs the system that the driver 
to be loaded is a vectored driver. This prevents the normal 
comparison of the driver symbol table file and the system symbol 
table file. 
Examples 
l. YMROLOA MME 
Loads the TU16 driver (MMDRV). 
2. VMRSLOA DKS /PAR=DRVFAR 
Loads the RKO5 driver (DKDRV) into DRVPAR. 
3. VMRTLOA URS/CTB=RHB 
Loads the RMO3 driver (DRDRV), using the RHB multidriver 
Notes 


1. On RSX-11M systems, you can LOAD drivers above the 124K-word 


limit. See the description of the FIX command for more 
information. 
2. Guidelines for building user-written, loadable device-driver 


tasks are defined in the RSX-11M Guide to Writing an I/O 
Driver and the RSX-11M-PLUS Guide to Writing an I/O Driver. 


3. The LOAD command requires that a driver's .TSK and .STB files 
reside in the same directory and on the same disk as the 
system image file you are working on. For example, the 
command : 


LOAD DT: 


requires that the files DTDRV.TSK and DTDRV.STB reside on the 
device SY:, under the current UIC. 


4. The LOAD command requires the following pool space: 


e If the driver data base is being loaded, the data base 
needs contiguous pool space equal to its size. 


@ In a mapped system, each interrupt entry in the driver 
needs pool space for an Interrupt Control Block (ICB). 


e If the driver is being loaded into a _ system-controlled 


partition, the Partition Control Block (PCB) needs pool 
space. 
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LOGICAL UNIT NUMBERS 


Use the LUN command to display the static LUN assignments for a 


specified task. Static assignments are those recorded in the task's 
disk image file, for example, those assignments specified at 
task-build time. The display consists of a list of physical device 


units in one column and their corresponding LUNs in an adjoining 
column. 


Format 
LUN[S] taskname 
Parameter 


taskname 


The name of the task whose LUNs you want to display. 


Example 


VMR=LUN XKE 
SYO: i 
SYOs 2 
CLOs 3 
TTS$ 4 
TLS. 3 
KO? 6 
hhae \« 


The display shows static assignments for LUNs 1 through 7 as 


recorded in the task image file header. No other LUNs are 
assigned statically to the task XKE. 
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Use the PARTITION command to display 


partition in the system image. 


a description 


of 


each 


memory 


The partition display consists of columns that specify the following: 


On RSX-11M-PLUS, the page aecompanying the cpabere ents name have 


Partition 
Partition 
Partition 
Partition 


Partition 


name 


Control Block address (in octal) 


base address (in octal) 


size (in octal) 


type 


Name of partition occupant(s) 


following. meanings: 


Format 


+ + multiuser task (read-o! 


14 


<> active task 


read-write name 


( ) driver © 


PAR[TITIONS ] 


Example 


The following example 


Name 


YMR 
SYSFAR 


PCB 


FAR 
035729 


SFLFAR 0354654 


DRVPAR OS 


T4110 
035324 
035249 
O35214 
QS5120 
935104 
NS4774 
O84? 30 
OS44EA 
0344620 
224584 
034470 
OS44R4 
93445460 
OSA Aya 
OSS04O 


Base 


00200300 
00210300 
00223300 
00223300 
00227000 
00230300 
00224100 
00235700 
00246400 
00247700 
OOPH1LS00 
00252700 
00310400 
00330400 
003327000 
00333300 
O0%24400 
QOFIS5OO 


is froma 


Size 


00010000 
090013000 
99140000 
09903500 
999013090 
00903409 
906001600 
00004200 
006001300 
990014600 
90001200 
00035500 
00020000 
900091490 
09001200 
90003190 
00900100 
060904400 


saved system: 


Type 


MAIN 

MAIN 

MATIN 

NRIVER 
NRIVER 
IREVER 
DRIVER 
IRTVER 
DRIVER 
UR IVER 
DRIVER 
RW COM 
DRIVER 
NRTVER 
TRIVER 
IRTVER 
MRIVER 
NRIVER 
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(THR?) 
CER) 
CTRS) 
(S$) 
(TIM? ) 
(iT?) 
C(TX$2 
CLES? 
ITTLOM 
(TTS) 
CRS) 
(UTS) 
(CO%) 
CNL 3) 
CMMs) 


the 


LIRFAR 
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O55 44 
033774 


TSTFAR O35500 


SECPOL 
GEN 
VME 


036454 
O35434 
035370 


00363300 
00363300 
00366309 
003466309 
904276300 
09476300 


00003000 
00003000 
00040000 
00040000 
00050000 
04701500 
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REASSIGN 
Use the REASSIGN command to reassign a task's logical unit numbers 
(LUNs) from one physical device unit to another. REASSIGN has no 
effect on the assignments for a task that is fixed or loaded in 
memory. The reassignments affect only the static assignments recorded 
in the task's disk image file. 
Format 

REA[LSSIGN] taskname LUN new: 
Parameters 


taskname > 


The name of the task for which the LUN is to be reassigned. 


LUN 
The logical unit number. 

new: 
The new device unit, which can be a physical, logical, or pseudo 
device. 

Examples 


1. VMR=REA LOMN 3% TTO% 
Reassigns LUN 3 of task LODN to physical device TTO:. 
2. VMRZREA TEST 3 XX? 


Reassigns LUN 3 of task TEST to logical device XX:. 
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REDIRECT 


Use the REDIRECT command to redirect all I/O requests from one 
physical device unit to another physical device unit. 


You cannot redirect the following: 

@ The pseudo device TI: 

e A device to the pseudo device TI: 

e A pseudo device to itself 

@ An attached device 

e A terminal to the null device. 
You can redirect a logged-in terminal to a device other than a 
terminal (except for the null device); however, it is not generally 
advisable to do so because terminal I/0 would be written to the 
device, which could destroy the boot block. If you do redirect a 
terminal to another type of device, you should redirect the terminal 
back to itself before you log out. 
Format 

RED[LIRECT] new:=old: 
Parameters 
“new: 

The new device unit to which requests will be redirected. 
old: 

The old device unit from which requests will be redirected. 
Examples 

1. VMRSRED TT3St=TTé3 

Redirects all I/O requests for device TT6: to device TT3:. 
2. VMRSREU TTI=LPe 


Redirects all I/O requests for device LPO: to device TTO:. 
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REMOVE 

Use the REMOVE command to delete a task name and, on RSX-11M-PLUS 
systems, a region name from the System Task Directory. Removing a 
task from the system image makes the task unrecognizable to the 
system. The action resulting from this command is the complement of 
INSTALL. 


The REMOVE command cannot remove an active task from a saved system. 
An example of such a task is SAV; an attempt to remove SAV from a 
saved system results in an error message. 


Format 

REM[LOVE] name[ /REG] 
Parameters 
name 


The name of the task, region, or directive common to be removed. 
/ REG 


(RSX-11M-PLUS systems only.) specifies that the name parameter 
you specify is the name of a region. 


You must specify this keyword when removing the directive 
commons. To remove the SORMONB use the following command line: 


VME > »REM QIRLIM/REG 


Note that whien’ you remove DIRIIM, you remove all of the directive 
commons in the system. 


Example 
VMR>REM SCAN 


Removes the task named SCAN from the System Task Directory. The 
task image file remains unaffected. 


Notes 


1. If a task or region that is the object of a REMOVE command is 
fixed, the command automatically unfixes the task from the 
system image. 


2. REMOVE automatically cancels all time-based schedule requests 
for the specified task. 


3. To remove a command line interpreter (CLI) task, you must 
first eliminate the CLI Parser Block (CPB) for the task with 
the MCR CLI /ELIM command on the running system. Then use 
the MCR SAVE command to update the system image file, invoke 
VMR, and remove the CLI. However, it is recommended that you 
work with CLIs exclusively with MCR on the - running 
system -- this includes eliminating and removing old CLIs, 
and installing and initializing new ones -- and then save the 
system. 
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An exception to this note is the primary MCR task (MCR...). 
The CPB for this task can never be eliminated and the task 
itself can be removed only with VMR. 


On RSX-11M-PLUS systems, a region cannot be removed if there 
are tasks installed in the system that reference that region. 


On RSX~11M systems, changes made in a common are made only in 
the memory image of the common. Therefore, a common does not 
retain changes when it is removed and then reinstalled. 


_ On RSX-1LIM-PLUS systems, changes" made in the memory image — of 
a common can be preserved when the common is chal hgan by 
pea the common with the /WB=YES option. 


| Yf the comnon is installed with the /weeves- Le yo 


_ REMOVE ‘command writes the common, with its changes, into its 


 eriginal task image file, replacing the original image. When 
the common is reinstalled, | ae new version of the common is 


placed in memory. 
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Use the RUN command to initiate the execution of an installed task. 
You can use the RUN command to initiate the execution of a task at any 
of the following time options: 

e At a time increment from the system image time 

@e At a time increment from clock unit synchronization 

@e At an absolute time of day 


e At one clock tick after the system bootstrap 


All of these options are available, with or without rescheduling. 
Each option has a separate format. 


On RSX-11M~PLUS, you cannot run a task whose name is in the form 
+0 eXXX Or xxx$$§. These tasks are prototype tasks, which are never 
executed. 

NOTE 


The correct value to be inserted in the clock queue 
for Formats 1 through 3 is derived from the current 
value of the system time stored in the system image. 
Therefore, the system image time must be set before 
any RUN requests are made or they may not occur at the 
correct time after the system is bootstrapped. 
Format 1 
RUN taskname time [/keyword(s) ] 
Runs the task at a time increment from the system image time. 
Parameters 
taskname 
The name of the task. A task name must be 1 to 6 characters. 
time 
The number of time units added to the current system image time 
to determine the time at which the task will run; or, when used 
with the /RSI keyword, the number of time units added to the time 


of the task's last completed run to determine the time at which 
the task will rerun. 
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The time parameter has the following format: 


mu 


where: 


The magnitude or number of time units to be clocked. 
The maximum number of time units you can specify 
depends on the type of time units you want to specify. 
You can specify the following time unit magnitudes: 


@e If you are specifying hours, m can be any positive 
number from 0 to 24(decimal). 


e If you are specifying minutes, m can be any positive 
number from 0 to 1440(decimal). 


e If you are specifying seconds, m can be any positive 
number from 0 to 32767(decimal). 


e If you are specifying clock ticks, m can be any 
positive number from 0 to 32767(decimal). 


If you are specifying a reschedule interval with the 
/RSI keyword and specify a magnitude (m) of 0, the 
Magnitude defaults to 1. For example, specifying 
/RSI=0H is the same as specifying /RSI=1H. 


The total time must not exceed 24 hours. The magnitude 
is decimal by default. 


The type of time units to be clocked. You can use 
Single letters to specify the following time units: 


H -—- Hours 


M - Minutes 


S - Seconds 
T - Ticks 
A tick is a clock interrupt. The rate at which 


interrupts occur depends on the type of clock installed 
in the system. 


For a line frequency clock, the tick rate is either 50 
or 60 ticks per second, corresponding to the line 
frequency. 


For a programmable clock, a maximum of 1000 ticks’ per 


second is available. (The frequency is selected at 
system generation. ) 
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/keyword(s) 


One or both of the following keywords: 


/RSI=time 
/uIc=[uic] 
Keywords 
/RSI=time 
Specifies the reschedule interval. The reschedule interval 
informs the system when you want it to rerun the task. Each time 
the interval of time you specify lapses, the system issues an 
initiation request for the task. The format for time is mu. See 
the description of the time parameter. 
The default is no rescheduling. 
/uIc=[uic] 
Specifies the UIC for the task. The task's UIC determines’ the 


file protection class (system,owner,group,world) to which the 
task belongs. When specifying a UIC, you must use square 


brackets ([ ]). 

The default is the UIC established for pseudo device CO:. 
Format 2 

RUN taskname sync [time][/keyword(s) ] 


Runs the task at a time increment from clock unit synchronization. 


The system determines the task run-time by waiting for the specified 
time unit (sync) and then waiting for the specified time increment 


(time) to elapse. 
Parameters 
taskname 


The name of the task. A task name must be 1 to 6 characters. 


sync 
Indicates the synchronization unit. You can specify 
following synchronization values: 
H ~- Synchronize on the next hour 
M - Synchronize on the next minute 
S - Synchronize on the next second 
T - Synchronize on the next tick 
time 
The time increment value, if present, is added to 


the 


the 


synchronization value to produce the time the task will be run. 


The format for specifying time is provided in Format l. 
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/keyword(s) 
One or both of the following: 
/RSI=time 
/uIc=[uic] 
These keywords are described under Format l. 
Format 3 
RUN taskname hh:mm:ss [/keyword(s) ] 


Runs the task at an absolute time of day. 


Parameters 
taskname 

The name of the task. A task name must be 1 to 6 characters. 
hh:mm:ss 

The absolute time of day at which the task will be run. The 


letters in the format are replaced with decimal numbers and 
indicate the following time units: 


hh - Hours 

mm — Minutes 

ss - Seconds 
/keyword(s) 


One or both of the following: 
/RSI=time 
/uIc=[uic] 
These keywords are described under Format l. 
Format 4 
RUN taskname [/keyword(s)] 
Runs the task one clock tick after the system bootstrap. 
Parameters 
taskname 


The name of the task. A task name must be 1 to 6 characters. 
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/keyword(s) 


One or both of the following: 


/RSI=time 


/UIc=[Luic] 


These keywords are described under Format 1. 


Examples 


l. 


VME ORUR XRE 13M 

Runs task XKE 15 minutes from the current system image time. 
GAR ORUN XEF LSM/RST=9OS/UTCHl S21) 

Runs task XKE 15 minutes from the current system image time, 
rescheduling it every 90 seconds. The task is running under 
UIC [3,1]. 

WMRORUM XKE H SM/EST=1H 

Synchronizes with the system image time on the next hour, 
runs the task XKE 5 minutes after synchronization, and 
reschedules the task to run every hour after the last 
completed run. 

YER XKE Sap 55300 

Runs task XKE at 5 minutes before midnight. 


UME RUM XRE/RS T= 2M 


Runs task XKE one clock tick after the system bootstrap and 
reschedules the task to run 2 minutes later. 
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SAVE 


Use the SAVE command to write the image of a system onto a_ sequential 
medium in bootable format. By using the SAVE command, you can copy an 
RSX-11S system or a foreign system onto a tape or a diskette. You can 
then transport the magnetic tape or diskette to another computer and 
bootstrap it, using a hardware bootstrap. (Refer to the description 
of the /IM switch in Section 10.4.) 


On paper tape, system images are created in absolute loader format and 
must be bootstrapped with the absolute loader. 


Format 

SAVLE] ddnn:[label][/keyword(s) ] 
Parameters 
ddnn: 


The device unit onto which the system image is written. The SAVE 
command accepts the following devices: 


CT: Tape cassette 

DD: TU58 DECtape II 

DT: DECtape 

DU: RX50 diskette/RA60 disk/RC25 disk (removable) 
DX: RXOl diskette 

DY: RX02 diskette 

MM: TE/TU16/TU45/TU77 magnetic tape 

MS: TS11/TSVO5/TU80 magnetic tape 

MT: TE/TU1O/TSO3 magnetic tape 

MU: TK50 cartridge tape/TU81 magnetic tape 
PP: Paper tape 


label 


The file label name that must be specified for all devices except 
paper tape. The label name can be 1 to 12 alphanumeric 
characters. 


Keywords: 
/BOOT=type: 


Specifies the type of boot block being used when the system image 
is saved. The options for type are DX: (for RXOls) and DY: 
(for RX02s). 


The /BOOT keyword allows you to use an RXOl drive to bootstrap a 
system that was saved using an RX02 drive in single-density mode, 
or to use an RX02 drive to bootstrap a system that was saved 
using an RXO1l drive in single-density mode. 


If you do not use /BOOT, the boot block for the type of device 
being used is written to the device. 
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/DENS=1600 


Specifies the bits per inch (bpi) density for the following 
9-track magnetic tapes: 


TE16 TU16 TU45 TU77 


These tapes use the device mnemonic MM:. 


Example 
Me ea AE eS 12 
In this example, the system image is written onto MT: in 
bootable format. System changes made by other VMR commands are 


also saved with the system image. 
Notes 


1. On RSX-11M and RSX-11S systems, the maximum memory size of a 
system is 124K-words. The SAVE command limits the size of 
Mapped systems for certain devices. If a mapped system is 
saved and its memory size is greater than the maximum size 
imposed by the SAVE command for the specified device, only 
the amount of memory equal to the maximum size (starting at 
physical location 0) is saved. 


The devices for which the SAVE command imposes a maximum size 
on saved system images are as follows: 


Paper tape punch (PP: ) 28K-words 
Cassette tape (CT:;) 28K-words 
RXO1 diskette’ (DX:) 123K-words 
RX02 diskette (DY:) 123K-words 


2. When you save RSX-11S systems on paper tape and you do not 
apply the /IM switch to the system's file name (refer to 
Section 10.4 for a description of the /IM switch), the last 
1000(octal) bytes of the system image are not written out. 


This allows space to accommodate the absolute loader. When 
you specify the /IM switch with the system's file name, the 
entire system image is written to paper tape. In this’ case, 


it is your responsibility to ensure that the system image is 
not so large that it overwrites the absolute loader. 


3. When you bootstrap systems on media other than paper tape, 
regardless of the size of the system image, the last 
1000(octal) bytes of physical memory are not copied to 
accommodate the bootstrap. 
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When you save a system on paper tape, contiguous blocks’ that 
contain only zeros and begin on a 32-word address are 
compressed into two words that contain the zero count. This 
compression significantly reduces both the amount of paper 
tape required and the time expended to create the tape and 
read it into memory. After the entire image has been loaded 
into memory, a short routine writes zeroes into the 
appropriate blocks of. memory before passing control to the 
bootstrapped system. 


Systems saved on a TE/TU1O/TSO3 9-track magnetic tape drive 
can be bootstrapped from a TE/TU16 drive, and the reverse. 


When you specify the /IM switch with the system file 
specification, the SAVE command always uses a bootstrap that 
does not enable memory management. 


None of the bootstraps require that a target RSX-11S system 
have a driver for the bootstrap device. 


Unless you specify /DENS=1600, when you save a system image 
to a magnetic tape drive that supports multiple densities, 
the drive is forced to 800 bpi before the SAVE operation is 
started. 
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SET 
Use the SET command to alter a number of system-wide characteristics. 
The SET command allows you to do the following: 

@e Set device characteristics for devices 

e Set default UICs for terminals 

@ Set system UIC 

e Set and display terminal status 

e Create and eliminate partitions 

@e Add space to the system dynamic memory 

@ Enable write-checking and seek optimization on devices that 


support it 


When using the SET command, a situation can arise in which the system 
fails to accept privileged user input. To avoid this, the system 
should have at least one nonslaved terminal and one _ privileged 
terminal. You need a privileged terminal because nonprivileged 
terminals cannot enter privileged commands. You need a enonslaved 
terminal because slaved terminals cannot enter unsolicited input to 
MCR. For more information, see the description of the niu eeiiaies 


On RSX-11M systems, an 


features that must be in 
keyword that requ | yst: ! 
the SET command , a error 1e gage. 


“ures Abe aie "Yisctea 


In addition, some of the SET keywords are supeorted With the 
full-duplex terminal driver only. The full-duplex terminal driver is 
a system generation option for RSX-11M systems, but is always included 
in RSX-1L1M-PLUS' systems. Note that if you select the full-duplex 
driver on RSX-11M, you must also select the GET/SET Multiple 
Characteristics option to SET or display any terminal-related 
characteristics. 


VMR permits only one keyword per command line. You can prefix most 
keywords by NO to negate or disable the function of the keyword. VMR 
returns a syntax error message when NO precedes a keyword for which it 
is illegal. 

Examples of the SET command follow the keyword descriptions. 


Format 


SET /keyword[=value] 
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Parameter 
/keyword[=value] 
The following table provides a functional listing of the SET 
keywords. You can use one keyword per command line with the SET 
command. 
Table 10-2 
SET Keywords 
Type Keywords 


Device /ABAUD[=ttnn: ] 

Characteristics 
/ANSI[=ttnn: ] 
/avo[=ttnn: ] 
/BLKMOD[=ttnn: ] 
/BRO[=ttnn: ] 
/BUF=ddnn:[size] 
/cRT[=ttnn: ] 
/pEC[=ttnn:] 
/EBC[L=ttnn: ] 
/ECHO[=ttnn: ] 
/EDIT[=ttnn: ] 
/ESCSEQ[=ttnn: ] 
/FDX[=ttnn: ] 
/FORMFEED[=ttnn: ] 
/HFILL=ttnn:[value] 
/HHTC=ttnn: J 
/HSYNC([=ttnn: ] 
/LINES=ddnn:[value] 
/LOWER[=ttnn: ] 
/OPTCL=ddnn:opttyp] 
/PARITY[=ttnn:[Loption]] 
/PASTHRU[=ttnn: ] 


(continued on next page) 
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Table 10-2 (Cont.) 
SET Keywords 


Type Keywords 
Device /PRINTER_PORT[=ttnn: ] 
Characteristics 
(cont.) /PRIV[=ttnn: ] 


/PUB[L=ddnn: ] 
/REGIS[=ttnn: ] 
/REMOTE[=ttnn:[speed]] 
/RPA[L=ttnn: ] 
/SERIAL[=ttnn:] 
/SLAVEL=ttnn:] 
/SOFT[=ttnn: ] 
/SPEED=ttnn:[recv:xmit] 
/TERM=ttnn:[type] 
/TTSYNC[=ttnn: ] 
/TYPEAHEAD[=ttnn:[size]] 
/UIc=[[Luic]:]:ttnn: 
/VFILL[=ttnn: ] 
/WCHK[=ddnn: ] 
/WRAP[=ttnn: ] 


Enable/Disable / LOGON 
Login 
Library, Network, /LIBUIC[=Luic]] 
or System UICs 
/NETUIC[=[uic]] 


/SYSUIC[=[uic]] 


Memory JAFF=[UNI BUS-mask] 
Allocation 
(see Notes) /BOT=pname: value 


/MAIN=pname[ :base:size:type] 
/NOMAIN=pname 
/MAXEXT[=size] 


(continued on next page) 
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Table 10-2 (Cont.) 
SET Keywords 


Type Keywords 
Memory /PAR=pname[ :base:size[:type]] 
Allocation ee el 
(cont.) /NOPAR=pname > 


/POOL[=top] 
/POOLSIZE[=value] 

/SECPOL 

/SUB=mname:sname[ :base:size] 
/NOSUB=mname : sname 


/TOP=pname:value 


Pool /PLCTL[C=CLhigh]({:Clow]£:Cfrsiz][:basep]]]j] 
Monitor Task 
System /RNDC[=nn ] 
Tuning 
/RNDH[=nn] 
/RNDLC=nn] 
/swec{=nn] 
/SWPRE[=nn] 
Keywords: 


/ABAUD[=ttnn: ] 


(Full-duplex terminal driver only.) Enables autobaud detection 
for the remote dial-up line for the specified terminal. The 
terminal driver samples the line's first input character, tries 
to determine the incoming speed, and sets the interface speed 
accordingly. 


When you omit the terminal specification, VMR displays all the 
terminals with autobaud detection. 


/NOABAUD[=ttnn: ] 
(Full-duplex terminal driver only.) Disables autobaud detection 
for the specified terminal. The terminal driver does not attempt 


to determine the incoming speed for the remote dial-up line. 


When you omit the terminal specification, VMR displays all the 
terminals that do not have autobaud detection. 
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/AFF=[UNIBUS-run-mask,...] 


(RSX-11M-PLUS multiprocessor systems only.) Specifies which 


I/O 


page will contain the device partition. This keyword is required 


for creating device partitions on the system. 


You must specify at least one URM. Enclose the URM(s) in square 


brackets ([ ]). 


If you specify more than one URM, you must’ separate them 


commas. For example: 
/AFF=[UBE, UBF, UBH] 


UNIBUS-run-mask 


by 


The three-letter name of the URM with which the device 
partition is associated. The following names are valid URM 


specifications: 


CPA UBE UBK UBP 
CPB UBF UBL UBR 
CPC UBH UBM UBS 
CPD UBJ UBN UBT 
You must specify at least one URM. If you specify more than one 


URM, you must separate them by commas. 


You must enclose the URM specification in square brackets ([ ]). 


For example, to create a device partition that is mapped to CPA's 


I/O page, enter the following command line: 


SET /PAR=DEVP:177600:200:DEV/AFF=[CPA] 


/ANSI{=ttnn: ] 


(Full-duplex terminal driver only.) Informs the system that the 
specified terminal supports ANSI escape sequences. 
When you omit the terminal specification, VMR displays all the 
terminals that have the ANSI characteristic set. 

/NOANSI[=ttnn: ] 
(Full-duplex terminal driver only.) Informs the system that the 
specified terminal does not support ANSI escape sequences. 
When you omit the terminal specification, VMR displays all 


terminals that do not have the ANSI characteristic set. 


/Avo[=ttnn: ] 


(Full-duplex terminal driver only.) Informs the system that the 
specified vT100-series terminal has the advanced video option. 


This option gives the terminal the capability to blink, bold, and 


flash parts of the screen, and to set the screen at 132(decimal) 
columns. 
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If the word SET-UP blinks in set-up mode, the terminal has 
advanced video option. See your system manager for 
information. 


When you omit the terminal specification, VMR displays all 
terminals that have the advanced video option. 


/NOAVO[=ttnn: ] 


(Full-duplex terminal driver only.) Informs the system that 
specified terminal does not have the advanced video option. 


When you omit the terminal specification, VMR displays 
terminals that do not have the advanced video option. 


/BLKMOD[=ttnn: ] 


(Full-duplex terminal driver only.) Enables local editing 
block-mode transmission for the specified terminal. 


When you omit the terminal specification, VMR displays all 
terminals that have the block-mode option enabled. 


/NOBLKMOD[=ttnn: ] 


(Full-duplex terminal driver only.) Disables local editing 
block-mode transmission for the specified terminal. 


When you omit the terminal specification, VMR displays all 
terminals that have the block-mode option disabled. 


/BOT=pname: value 


the 
more 


the 


the 


all 


and 


the 


and 


the 


Directs VMR to move the bottom boundary of the _ specified 
system-controlled partition (pname) up or down the = amount 


indicated by the value parameter. The /BOT keyword modifies 


the 


bottom boundary of a partition even though it has tasks installed 


in it. If you modify the partition so that it becomes too 


small 


to hold the tasks installed in it, VMR displays a warning message 


but modifies the partition anyway. 
pname 

The 1l- to 6-character alphanumeric partition name. 
value 


The number of 64-byte blocks. 


The value parameter can be supplied in five formats: 
+value, -value, value, +* or *, and -*. These are described 


as follows: 


+value 


Moves the partition's bottom boundary up the amount 
indicated by the specified value. Moving the bottom 


boundary up makes the partition smaller. 
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NOTE 


You must supply the value in the same units as 
those of the base and size parameters for the 
/PAR keyword. 


~value 


Moves the partition's bottom boundary down the amount 
indicated by the specified value. Moving the bottom 
boundary down makes the partition larger. 


value 


Moves the partition'’s bottom boundary until the total 
partition size is equal to the specified value. 


+P OK * 


Moves the partition's bottom boundary up as far as 
possible. Note that using this format will cause the 
bottom boundary to move up to the bottom of the first 
fixed task or fixed driver loaded into the partition at 
the time the /BOT keyword is executed. If there is 
nothing loaded into the partition, it assumes a size of 
one 64-byte block. 


Moves the partition's bottom boundary down as far as 
possible. Using this format will cause the bottom 
boundary of the partition to move down to the top 
boundary of the partition below it, or to the top of 
the Executive pool if the partition is the lowest 
partition in memory. 


/BRO[=ttnn: ] 
Enables the broadcast option for the specified terminal. The 
terminal can receive messages sent from other terminals with the 


MCR BROADCAST command. 


When you omit the terminal specification, VMR displays all the 
terminals that can receive messages. 


The /BRO keyword is valid only on systems with multi-CLI support. 
/NOBRO[=ttnn: J] 


Disables the broadcast option for the specified terminal. The 
terminal cannot receive messages sent from other terminals. 


When you omit the terminal specification, VMR displays all the 
terminals that cannot receive messages. 


The /NOBRO keyword is valid only on systems with multi-CLI 
support. 
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/BUF=ddnn:[size] 


Sets the default buffer size of the specified device. The size 
you specify must be from 0 to 255(decimal). (For a terminal, the 
size you specify must be greater than or equal to 15(decimal)). 
The /BUF keyword is particularly useful for defining line printer 
width (for example, 80 or 132 columns). 


When you omit the size specification, VMR displays the current 
buffer size of the device. 


/crRT{=ttnn: ] 


Informs the system that the specified terminal is a cathode ray 
tube (CRT) terminal and enables the backwards deletion option. 


When the backwards deletion option is enabled, pressing the 
RUBOUT or DELETE key moves the printing position one space to the 
left and erases any character displayed in that position. 


When you omit the terminal specification, VMR displays all the 
terminals that are defined as CRTs. 


/NOCRT[=ttnn: ] 


Informs the system that the specified terminal is not a CRT and 
disables the backwards deletion option. 


When you omit the terminal specification, VMR displays all the 
terminals that are not defined as CRTs. 


/DEC[L=ttnn: ] 


(Full-duplex terminal driver only.) Indicates that the specified 
terminal is upward-compatible with the VT100-series of terminals. 


When you omit the terminal specification, VMR displays all the 
terminals that are upward-compatible. 


/NODEC([=ttnn: ] 
(Full-duplex terminal driver only.) Informs the system that the 
specified terminal is not upward-compatible with the VT100-series 


of terminals. 


When you omit the terminal specification, VMR displays all the 
terminals that are not upward-compatible. 


/EBC[=ttnn: ] 
(Full-duplex terminal driver only.) Enables the 8-bit character 
option. The terminal driver passes all eight bits of the 


characters to the specified terminal. 


When you omit the terminal specification, VMR displays all the 
terminals that have the 8-bit character option enabled. 
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/NOEBC[=ttnn: ] 


(Full-duplex terminal driver only.) Disables the 8-bit character 
option. The terminal driver clears the eighth bit of the 
characters before passing them to the device. 


When you omit the terminal specification, VMR displays all the 
terminals that do not have the 8-bit character option enabled. 


/ECHO[=ttnn: J 


Enables the echo option. The terminal driver displays each 
character that is typed on the specified terminal. 


When you omit the terminal specification, VMR displays all the 
terminals that have the echo option enabled. 


/NOECHO[=ttnn: ]} 


Disables the echo option. The terminal driver does not display 
the characters that are typed on the specified terminal. 


When you omit the terminal specification, VMR displays all the 
terminals that have the echo option disabled. 


/EDIT(=ttnn: ] 


(Full-duplex terminal driver only.) Informs the system that the 
specified terminal can perform ANSI-defined advanced editing 
functions. The VT102 is an example of such a terminal. 


When you omit the terminal specification, VMR displays all the 
terminals that can perform the advanced editing functions. 


/NOEDIT[=ttnn: J] 


(Full-duplex terminal driver only.) Informs the system that the 
specified terminal cannot perform ANSI-defined advanced editing 
functions. 


When you omit the terminal specification, VMR displays all the 
terminals that cannot perform the advanced editing functions. 


/ESCSEQ[=ttnn: ] 


Enables the recognition of escape sequences from the _ specified 
terminal. The terminal driver treats the ESC character as the 
beginning of an escape sequence rather than as a line terminator. 
(See the RSX-11M/M-PLUS I/O Drivers Reference Manual for further 
information about escape sequences.) 


When you omit the terminal specification, VMR displays all the 
terminals that recognize escape sequences. 


/NOESCSEQ[=ttnn: J 


Disables the recognition of escape sequences at the specified 
terminal. 


When you omit the terminal specification, VMR displays all the 


terminals that do not support the recognition of escape 
sequences. 
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/FDxC=ttnn:] 
(Full-duplex terminal driver only.) Enables the full-duplex 
option. The terminal driver accepts input from the specified 
terminal while simultaneously outputting to it. 


When you omit the terminal specification, VMR displays all the 
terminals that have the full-duplex option enabled. 


/NOFDX[=ttnn: ] 
(Full-duplex terminal driver only.) Disables the full-duplex 
option. The terminal driver will not process input and output 


from the specified terminal simultaneously. 


When you omit the terminal specification, VMR displays all the 
terminals that do not have the full-duplex option enabled. 


/FORMFEED[=ttnn: ] 


Informs the system that the specified terminal supports a 
hardware form feed. 


When you omit the terminal specification, VMR displays all the 
terminals that support hardware form feeds. 


/NOFORMFEED[=ttnn: ] 


Informs the system that the specified terminal does not support a 
hardware form feed. 


When you omit the terminal specification, VMR displays all the 
terminals on the system that do not support hardware form feeds. 


/HFILL=ttnn:[value] 
(Full-duplex terminal driver only.) Specifies the number of fill 
characters (value) that the terminal driver is to place after a 
carriage return when outputting to the specified terminal. The 
value is a number from 0 through 7. 


When you omit the value parameter, VMR displays the number of 
fill characters currently being output by the terminal driver to 
the specified terminal. 


/BHHTC=ttnn: J 


(Full-duplex terminal driver only.) Indicates that the specified 
terminal supports a hardware horizontal tab. 


When you omit the terminal specification, VMR displays all the 
terminals on the system that support a hardware horizontal tab. 


/NOHHT[=ttnn: ] 


(Full-duplex terminal driver only.) Indicates that the specified 
terminal does not support a hardware horizontal tab. 


When you omit the terminal specification, VMR displays all the 
terminals that do not support a hardware horizontal tab. 
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/HSYNC[=ttnn: ] 


(Full-duplex terminal driver only.) Enables host-terminal 
synchronization. 


Host-terminal synchronization controls the typeahead buffer to 
prevent it from overflowing. When the typeahead buffer is full, 
the system temporarily locks the terminal keyboard by generating 
a CTRL/S which prevents you from entering more information. 


Once the terminal is able to transmit all of the information in 
the typeahead buffer to the operating system, the system unlocks 
the keyboard by generating a CTRL/Q which allows the terminal to 
receive input. 


The /HSYNC keyword is recommended for users with terminals that 
transmit information in blocks, for example, the DIGITAL VT131 
and VT132 terminals. It is also recommended for users with 
terminals that emulate these models. If you do not have one of 
these terminals it is unlikely that you will fill the typeahead 
buffer. To change the size of your typeahead buffer, use the 
/TYPEAHEAD keyword. 


/HSYNC is the default for the VT100-series of terminals. 


When you omit the terminal specification, VMR displays all the 
terminals that have host-terminal synchronization. 


/NOHSYNC[=ttnn: J 


(Full-duplex terminal driver only.) Disables host-terminal 
synchronization for the specified terminal. 


Disabling synchronization means that when the typeahead buffer 
for the terminal is full, the system does not lock the keyboard, 
and subsequent input is lost. 


/NOHSYNC is the default for VT52 terminals. 


When you omit the terminal specification, VMR displays all the 
terminals that do not have host-terminal synchronization. 


/LIBUIC[=[uic]] 
(RSX-11M-PLUS systems only.) Directs the INSTALL command to 
search the specified UIC in response to a RUN $file or INS $file 
command when the file is not in the system UIC. 


The UIC is in the format [g,m], where g and m are octal numbers 
from 1 through 377(octal) that represent a group and member 


number, respectively. You must use square brackets ([ ]). When 
you omit the UIC specification, VMR displays the current library 
UIC. 


The default library UIC is [3,54]. 
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/LINES=ddnn: [value] 


(Full-duplex terminal driver only.) Establishes the number of 
lines per page on the specified device. The value is a number 
from 1 through 255(decimal). If you specify a number that is 
larger than the number of lines per page possible for a given 
device, VMR defaults to the largest number possible for that 
device. 


When you omit the value parameter, VMR displays the lines per 
page for the specified device. 


/LOGON 
Enables logging in on terminals in a multiuser protection system. 


/LOGON and /NOLOGON clear and set a flag checked by the HELLO 
command when a user attempts to log in on a terminal. 


/NOLOGON 


Disables logging in on terminals in a multiuser protection 
system. 


/LOGON and /NOLOGON clear and set a flag checked by the HELLO 
command when a user attempts to log in on a terminal. 


/NOLOGON provides a means of preventing users from accessing the 
system during such activities as system maintenance or account 
file maintenance. 


/LOWER[=ttnn: ] 


Specifies that lowercase characters are not converted to 
uppercase when received from the specified terminal. 


When you omit the terminal specification, VMR displays all the 
terminals for which lowercase characters are not converted. 


/NOLOWER[=ttnn: ] 
Resets the terminal characteristics of the specified terminal so 
that lowercase characters received on input are automatically 
converted to uppercase and echoed as uppercase. 


When you omit the terminal specification, VMR displays all the 
terminals for which conversion to uppercase is specified. 


eh arce :base: size: type] — 


(RSX-21M systems only. y ‘Establishes: a main partition. 


_pname : 


‘The to ‘6-character alphanumeric partition name. 
coo Co . oo . 


The physical bane. address of the ‘partition specified as a 
number of 64-byte blocks. : Lee es 
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size 


‘You can enter base and 


The size of the bos talon specified as a eae fot 64-byte 
blocks. The maximum size is 0 to 1920K-words for a task, common , 


or matt PRestetonys | 


The partition type. You can assign the following partition. 

types: z ae ; | : ae 
sys ee 
Assign an sys partition type. for a main partition. 
Main partitions are miiogates: for user tasks and 
loadable drivers. : : 


‘Assign a COM partition type for a common partition. 
“Assign a DEV artition type for a common partition that 
Maps the device gisters. Device partitions are 
allocated for ns that are used by tasks to 

BEESEe the de sale on the Lae Bases 

TASK Bae 


“Assign a ‘TASK 


[oan | Octal sett 
mmmn. - —s«éDecimal (nnnn.*64. § 
nnnK —i“éOOCthal K (nnn*4000) 
nnn -K a Decimal K (ann. *2048. , 


‘where nnnn ib a anbert to which a multiplication factor is 


applied to determine aac value used. Valid ranges of calculated 
values are: a 4 


Octal -Qembaeet177777 0<size<2000 


Decimal = = _-«0.. <"base<65535 0.<size<1024. 
Octal K  QK<#base<3777K © OK<size<40K 


Decimal K — 0. Kesbage<2047 -K  0- K<size<32.K 


‘For. system-controlled ‘partitions, size may range from 0 to 1920K 
or: any valid Fepreqentation of these limits. 


‘You can speci fy the base address of a partition with a wildeard 

(*) for TASK or sys partitions in a mapped system. When you 
specify a wildcard, VMR creates a partition at the lowest address 
“posetpie for a. partition of the pal es yeu have specified. 
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/MAXEXT[=size] 


Establishes the maximum size to which a task can extend itself 
beyond its mapped array area by means of the EXTEND TASK 


directive. (See the RSX-11M/M-PLUS and Micro/RSX Executive 
Reference Manual for a description of the directive.) The size is 
given in units of 32(decimal)-word blocks. The maximum size 


allowed is 1777(octal) for systems without memory management and 
177777 (octal) for systems with memory management. 


You can specify size in the following formats: 


Specified Resulting 
Size Size 
n (n*100) octal 
n. (n*64.) decimal 
nK (n*4000) octal 
n.K (n*2048.) decimal 
* 1777(octal) maximum for systems without PLAS 


177777(octal) maximum for systems with PLAS 


When you omit the size specification, VMR displays the current 
maximum extension size in 100(octal)-byte units. 


The /MAXEXT keyword is valid only on mapped RSX-11M systems that 
have selected the EXTEND TASK directive option during system 
generation and on all RSX-11M-PLUS systems. However, you can use 
both the unmapped and mapped versions of VMR to establish the 
maximum extension size for tasks. 


/NETUIC([=[uic]] 
Specifies the UIC in which all DECnet-related tasks are _ stored. 


The /NETUIC keyword applies only to systems that select the 
external communication products option during system generation. 
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The UIC is in the format [g,m], where g and m are octal numbers 
from 1 to 377(octal) that represent a group and member number, 
respectively. You must use square brackets ([ ]). 


When you omit the UIC specification, VMR displays the current 
network UIC. 
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2 ecm K. (nnn. #2048. a 
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For SYS partitions, gize ca 
representation © of the : 
inputs for. size allocate a 2 


40 


“You can specify the base address. of a . partition with a wila 

*) at 
Lowest address. possible. for a partition ‘of the: “size you 
spect tiiedy | Lae ee 


You can also aeeci the bike of a eels with a es deer, 
When you specify a wildcard, VMR creates the largest possible 
partition sie meet at the pase address you ppecstiee } in the base 
aoeka ie ee Poe 7 - 


al ey tl 
_ existing pa: 


lies you 4 
 -walues 0! the 

- partition is a ma 

of all its Sent pa 


/NOPAR=pname 


(rex-1in-pe 
the system. ‘* 
list of partitions ar 3 - are 
installed in or att ct -” part n is not 
eliminated, and VMR ar e oe 


/PARITY[{L=ttnn:[Loption]] 


Enables parity generation and checking. The option you specify 
selects the state of the parity bit. 


Parity checking is used to verify the transmission of data 
between a terminal and the operating system. Verification occurs 
by sending an extra bit with each character called the parity 
bit, which serves as a check that the transmitted character was 
received properly. 


If you do not enable parity checking, parity bits are not 
transmitted. 


The options for /PARITY are EVEN and ODD. The state of the 
parity bit, which is either 0 or 1, is determined by the option 
you specify. If you do not specify an option, VMR defaults’ to 
EVEN. 
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If you specify /PARITY=ttnn:EVEN, either a 0 or 1 is added, to 
make the total number of "1" bits even. If you specify 
/PARITY=ttnn:ODD, either a 0 or 1 is added, to make the _ total 
number of "1" bits odd. The system checks parity on input from a 
terminal. The terminal checks parity on output from the system. 


A parity check does not return an error when an EVEN parity is 
specified and an even number of bits are counted, or, when an ODD 
parity is specified and an odd number of bits are counted. 


Note that the terminal hardware must be set to the same mode of 
parity generation and checking as the system for correct data 
transmission to occur. On the VT200-series of terminals, this is 
done through the terminal's SET-UP mode. 


The /PARITY keyword is not related to the /EBC keyword. The 
8-bit character option clears the eighth data bit only. 


When you omit the terminal specification, VMR displays all the 
terminals that have parity checking enabled. 


/NOPARITY[=ttnn: ] 


Disables parity generation and checking for the specified 
terminal. Data transmitted between the terminal and the system 
is not verified. 


When you omit the terminal specification, VMR displays all the 
terminals that do not have parity generation and checking 
enabled. 


/PASTHRU[=ttnn: ] 


(Full-duplex terminal driver only.) Requests the system to ignore 
the original function of special characters typed at the 
specified terminal and, instead, pass them to a program in their 
binary form. 


/PASTHRU allows you to suppress standard operating system 
responses to special characters (for example, CTRL/C and CTRL/O), 
thereby controlling output to the terminal screen. 


While /PASTHRU is enabled, the terminal does not recognize any 
control characters, except CTRL/S and CTRL/Q if it is set to 
/TTSYNC, nor does it respond to  carriage-return/line-feed 
characters. 


If your terminal does not seem to be working properly, it may 
have been set to /PASTHRU. 


When you omit the terminal specification, VMR displays all the 
terminals that have been set to /PASTHRU. 


/NOPASTHRU[=ttnn: ] 
(Full-duplex terminal driver only.) Requests the system to 


recognize the original function of special characters typed at 
the specified terminal. 
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When you omit the terminal specification, VMR displays all the 
terminals that have not been set to /PASTHRU. 


/NOPASTHRU is the default. 
/PLCTL[=Chigh][:Clow][:Cfrsiz][:basep]]]] 

(Systems with pool monitoring support only.) Sets the pool limit 

parameters used by the Pool Monitor Task (PMT). The following 

list defines the parameters: 

high 


The high pool limit in bytes. 


low 
The low pool limit in bytes. 

frsiz 
The minimum byte size of the largest free pool block 
required for avoiding low pool actions by the Pool Monitor 
Task (PMT...). 

basep 


The base task priority, which is the lowest priority a 
nonprivileged task can have and still be eligible for memory 
contention during times of low pool; this priority remains 
in effect until pool conditions improve. (Note that only 
those tasks requested to run while the system is in a low 
pool state are affected). 
The following list defines the limits of the parameters: 

84. <=low <=high <=total size of system pool 
84. <=frsiz <=high 

O. <=basep <=250. 


The following list gives the defaults for the parameters: 


high 1600. bytes 
low 600. bytes 
frsiz 200. bytes 


basep 51. 


See Chapter 13 for information on determining values for 
parameters. 


When you omit the parameter specifications, VMR displays’ the 
current parameters for the system. 
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/POOL[=top] 
Increases the size of the dynamic storage region (pool). 
top 


The first location in memory used for partition allocation. 
You specify top in units of 64-byte blocks, in octal or 
decimal. 


When you do not specify top, VMR displays the virtual 
address of the top of the Executive, the size of the longest 
block of pool space in words, the total number of words in 
the pool, and, on RSX-11M-PLUS, the lowest physical address 


at which a partition can start. (You can use the address 
when calculating partition layouts for systems supporting 
kernel data space. If your system is not a kernel data 


space system, this value is always equal to the virtual 
address of the top of pool.) The display's format is: 


POOL=top :max:total[:par] 


where top is given in units of 64-byte blocks, max and total 
are in decimal words, and par is the lowest physical address 
(32-word blocks). 


You can also specify top by using a wildcard (*). The 
wildcard directs VMR to supply the maximum amount of pool 
possible. Specify the wildcard as follows: 


/POOL=* 
If you request more pool than can be supplied, VMR prints a 
warning message and supplies the maximum amount of pool 


possible. 


/POOLSIZE[=value] 


Increases the size of the dynamic storage region (pool). The 
value you specify indicates the total amount of pool to be 
allocated. : 


If you do not specify a value, VMR dispiays the virtual address 
of the top of the Executive, the size of the longest block of 
pool space in words, the total number of words in the pool, and 
on RSX-1L1M-PLUS systems, the lowest physical address at which a 
partition can start (32-word blocks). 


The /POOL and /POOLSIZE keywords perform the same function. 
/POOL allows you to specify the top of pool. /POOLSIZE allows 
you to specify the total size of pool. 

/PRINTER_PORT[=ttnn: ] 
(Full-duplex terminal driver only.) Informs the system that the 
specified terminal has a printer port. The VT200-series of 


terminals, for example, has printer ports. 


When you omit the terminal specification, VMR displays all the 
terminals that have a printer port. 
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/NOPRINTER_ PORT[=ttnn: ] 


(Full-~duplex terminal driver only.) Informs the system that 


specified terminal does not have a printer port. 


When you omit the terminal specification, VMR displays 
terminals that do not have a printer port. 


/PRIV[=ttnn: ] : 
Sets the specified terminal to privileged status. 


When you omit the terminal specification, VMR displays 
privileged terminals in the system. 


/NOPRIV[=ttnn: ] 
Sets the specified terminal to nonprivileged status. 


When you omit the terminal specification, VMR displays 
nonprivileged terminals in the system. 


/PUB[=ddnn: ] 
Establishes the specified device as a public device. 


When you omit the device specification, VMR displays 
public devices in the system. 


/NOPUB[=ddnn: ] 
Causes the specified device to lose its public status. 


When you omit the device specification, VMR displays 
nonpublic devices in the system. 


/REGIS[=ttnn:] 


all 


all 


all 


all 


all 


(Full-duplex terminal driver only.) Informs the system that 


specified terminal supports the ReGIS graphics set. 


the 


the 


the 


the 


the 


the 


the 


The VT125 and the VT240 terminals both support the ReGIS graphics 


set. 


When you omit the terminal specification, VMR displays 


terminals that support the ReGIS graphics set. 


/NOREGIS[=ttnn: ] 


(Full-duplex terminal driver only.) Informs the system that 


all 


specified terminal does not support the ReGIS graphics set. 


When you omit the terminal specification, VMR displays 


terminals that do not support the ReGIS graphics set. 
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/REMOTE[=ttnn:[speed]] 


Informs the system that the specified terminal is connected to a 
modem and can be connected to the system by means of a dial-up 
network. The terminal has a line to the one of the following 


multiplexers: 
DH11 DLV11 
DHU11 DZ11 
DHV11 DZQ11 
DL11 DZv11 


Specifying speed establishes the initial speed (answer speed) of 
the remote dial-up line for the specified terminal. You can 
specify an answer speed only for the following variable-speed 


multiplexers: 
DH11 DZ11 
DHU11 DZQl1 
DHV11 DZV1l 


You cannot specify an answer speed for a DL11l or DLV11 
multiplexer. 


For the DH11 multiplexer, you can specify the following speeds: 


0 300 
50 600 
75 1200 

110 1800 
134.5 2400 
150 4800 
200 9600 


EXTA (user-specified speed A) 
EXTB (user-specified speed B) 


For the DHU11 and DHV11l multiplexers, you can specify the 
following speeds: 


75 1800 

10 2000 
134.5 2400 
150 4800 
300 9600 
600 19200 
1200 


For the DZ11, DZQl1, and DZV11l multiplexers, you can specify the 
following speeds: 


50 1800 

75 2000 
110 2400 
134.5 3600 
150 4800 
300 7200 
600 9600 
1200 
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When you omit the terminal specification, VMR displays all the 
remote terminals. 


When you omit the speed specification, the current setting for 
the terminal remains in effect. 


/NOREMOTE[=ttnn: ] 


Establishes the terminal's line as a local line that is not 
connected to a modem. 


When you omit the terminal specification, VMR displays all the 
local terminals. 


/RNDC[L=nn] 


Defines the length of the Executive round-robin scheduling 
interval in ticks. 


The length value (nn) is assumed to be octal, unless you place a 
period (.) after the value. The minimum value for nn is 0. See 
the RSX-11M System Generation and Installation Guide or the 
RSX-11M-PLUS System Generation and Installation Guide for more 
information. 


When you omit the length specification, VMR displays the current 
value for the interval. 


/RNDH[=nn] 


Defines the highest priority, from 1 to 250, that will be 
considered for Executive round-robin scheduling. 250 is the 
highest priority and 1 is the lowest priority you can assign. 
Therefore, a priority of 200 takes precedence over a priority of 
199. 


The priority you enter is assumed to be octal unless you place a 
period (.) after the number. 


The priority you specify must be higher than the one _ specified 
with the /RNDL keyword. See the RSX-11M System Generation and 
Installation Guide or the RSX-11M-PLUS System Generation and 
Installation Guide for more information. 


When you omit the priority class, VMR displays the current value 
for the priority. 


/RNDL[=nn] 
Defines the lowest priority, from 1 through 250, that will be 
considered for Executive round-robin scheduling. 250 is the 
highest priority and 1 is the lowest priority you can assign. 
Therefore, a priority of 200 takes precedence over a priority of 
199. 


The priority you enter is assumed to be octal unless you place a 
period (.) after the number. 
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The priority class must be lower than the one specified with the 
/RNDH keyword. See the RSX-11M System Generation and 
Installation Guide or the RSX-11M-PLUS System Generation and 
Installation Guide for more information. 


When you omit the priority class, VMR displays the current value 
for the priority. 


/RPA[=ttnn: ] 


(Full-duplex terminal driver only.) Enables the read-pass-all 
option. The terminal driver passes all characters input at the 
Keyboard to the terminal's input buffer. 


When you omit the terminal specification, VMR displays all the 
terminals on the system that have the read-pass-all option 
enabled. 


/NORPA[=ttnn: ] 


(Full-duplex terminal driver only.) Disables the read-pass-all 
option. The terminal driver does not pass special function 
characters (for example, CTRL/C) input at the keyboard to. the 
terminal's input buffer. 


When you omit the terminal specification, VMR displays all the 
terminals on the system that have the read-pass-all option 
disabled. 


/SECPOL 


(RSX-11-M-PLUS. system 


7 scondaey. pool use in the 
yet ‘The Geephay SS 


FORmAe 
SECPOL=secér: isecsi 
secfr 


‘The umber of ‘free ry pool in units of 
- 32(decimal)-word b oo ae 
Lee 


The size of ‘secondary pool in units of 32(decimal)-word 
blocks. A ee 


The percentage of free blocks in secondary pool. _ 


u mL PLUS eyetoue. only.) Causes imodeiced input Geen the 
Japenttice: terminal tO ete (procesecd serially, rather than in 
parallel. ee 2 : 
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/SLAVE[=ttnn: ] 


Establishes the specified terminal as one that can enter data 
only if it is solicited by a task. Therefore, the specified 
terminal always rejects unsolicited input (other than CTRL/O, 
CTRL/Q, and CTRL/S). 


When you omit the terminal specification, VMR displays all the 
terminals currently classified as slaved. 


/NOSLAVE[=ttnn: ] 
Sets the specified terminal to nonslaved status. 


When you omit the terminal specification, VMR displays all the 
terminals currently classified as nonslaved. 


/SOFT[=ttnn: ] 
(Full-duplex terminal driver only.) Informs the system that the 
specified terminal can accept software-defined character sets. 


The VT200-series of terminals can accept these character sets. 


When you omit the terminal specification, VMR displays all the 
terminals that accept software-defined character sets. 


/NOSOFT[=ttnn: ] 


(Full-duplex terminal driver only.) Informs the system that the 
specified terminal cannot accept software-defined character sets. 


When you omit the terminal specification, VMR displays all the 
terminals that do not accept software-defined character sets. 
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/SPEED=ttnn:[recv:xmit] 
Establishes the receive and transmit speed for terminals attached 
to the system through a DH11, DHU11, DHV11, DZ11, DZQl11, or DZvV1l 
variable-speed multiplexer. The values are described as follows: 


recv 


the recv value is the ‘speed at which characters are input to 
the computer from the terminal. 


xmit 


the xmit value is the speed at which characters are output 
to the terminal from the computer. 


You must specify both the recv and xmit values when setting the 
speed. If you do not specify either value, VMR: displays the 
current settings. 


For the DH11 multiplexer, you can specify the following speeds: 


0 300 
50 600 
75 1200 

110 1800 
134.5 2400 
150 4800 
200 9600 


EXTA (user-specified speed A) 
EXTB (user-specified speed B) 


For the DHU11 and DHV11 multiplexers, you can specify the 
following speeds: 


75 1800 
110 2000 
134.5 2400 
150 4800 
300 9600 
600 19200 

1200 


For the DZ1l, DZQl11, and DZV11 multiplexers, you can specify the 
following speeds: 


50 1800 

75 2000 
110 2400 
134.5 3600 
150 4800 
300 7200 
600 9600 
1200 


If you have a DZ11l, DZQl11, or DZV1l multiplexer, the receive and 
transmit speeds must’ be the same because these multiplexers do 
not support split speeds. 
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/SUB=mname:sname[ :base:size] 

(RSX-11M systems only.) Establishes a subpartition. 

Subpartitions can be established only in user-controlled main 

partitions. The values are described as follows: 

mname 
The l= to 6-character main partition name. The subpartition 
being defined becomes a subpartition in the named main 
partition. 

sname 
The l- to 6<character subpartition name. The subpartition 
being defined becomes a subpartition of the main partition 
specified in mname. 

base 


The physical base address of the subpartition, specified as 
a number of 64-byte blocks. 


size 


The size of the subpartition, specified as a number of 
64-byte blocks. ee 


Base and size may be entered in any of the following formats; 
nmnnn is a number to which the system applies a multiplication 
factor to determine the value used. 


Format Calculated Value 

n Octal (nnnn*100) 

n. Decimal (nnnn.*64.) 

nK Octal K (nnn*4000) 

n.K Decimal K (nnn.*2048.) 


Valid ranges for calculated values are: 


Octal 0<=base<10000 0<size<2000 
Decimal 0.<=base<4096. 0.<size<1024. 
Octal K OK <=base<200K OK<size<40K 


Decimal K 0.K<=base<2047 .K 0.K<size<32.K 
Example: 


Any of the following designations for size will allocate a 
2048(decimal)-byte subpartition: 


40 
32. 
1K 
1.K 


If base and size are omitted, VMR displays the current values for 
the named subpartition. 
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/NOSUB=mname : sname 


(RSX-11M systems only.) Eliminates the specified subpartition 
from the main partition. 


/swec[=nn]J 


Defines the number of clock ticks for a single Executive swapping 
interval. 


The number of clock ticks (nn) is in the range ) to 
45,568(decimal). The number of clock ticks is assumed to be 
octal unless you place a period (.) after the number. 


See the RSX-11M System Generation and Installation Guide or the 


RSX-11M-PLUS System Generation and Installation Guide for more 
information. 


When you omit the clock ticks specification, VMR displays’ the 
current value for the interval. 


/SWPRE=nn] 
Defines a priority range for Executive swapping. 


The priority number (nn) is in the range 0 through 127. 127 is 
the highest priority and 0 is the lowest priority you can assign. 
Therefore, a priority of 100 takes precedence over a priority of 
99. 


The priority you enter is assumed to be octal unless you place a 
period (.) after the priority number. 


The value for the /SWPR keyword affects the installed priority of 
all tasks. Each task is initiated at its installed priority, 
plus the value for nn as assigned in /SWPR=nn (priority + nn). 
While the task is executing, its priority is decremented until it 
becomes the installed priority minus the value for nn (priority 


- nn). When the priority reaches this lower limit, the task is 
swapped out so that another task with a higher priority can 
execute. The priority for the new task changes in the same way. 


See the RSX-11M System Generation and Installation Guide or the 
RSX-11M-PLUS System Generation and Installation Guide for more 
information. 


When you omit the range specification, VMR displays the current 
value for the priority range. 


/sysuic(=[uic]] 
Establishes the UIC for the system and all system tasks. The UIC 
has the format [g,m], where g and m are octal numbers that 


represent a group and member number, respectively. 


On most unmapped systems, the system UIC is [1,50]. On most 
mapped systems, the system UIC is [1,54]. 
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The UIC specified with the /SYSUIC keyword also becomes’ the 
default UIC used by the LOAD command and the install-run-remove 
option of the MCR RUN command. 


When you omit the UIC specification, VMR displays the current 
system UIC. 


/TERM=ttnn:[type] 


(Full-duplex terminal driver only.) Establishes the terminal type 
of the specified terminal. When VMR sets the terminal type, it 
automatically sets the HFILL, VFILL, CRT, FORMFEED, and HHT 
characteristics for the terminal. The standard terminal types 
are as follows: 


ASR33 LA34 LA210 VT52 VT125 
ASR35 LA36 LNO3 VT55 VT131 
DTCOL LA38 LQPO2 VT6l VT132 
KSR33 LA50 LQPO3 VT100 VT2XX 
LA12 LA100 PC3XX VT101 
LA30S LA120 VTO5B VT102 
LA30P LA180S vVT50 VT105 


If you specify a terminal type that is unknown to VMR, VMR_ does 
not set any device characteristics for the terminal. However, 
VMR stores the value you have specified in the Unit Control 
Block (UCB). 


When you omit the type parameter, VMR displays the terminal type 
of the specified terminal. 


VMR also accepts an alternate form of the command. You can 
specify the terminal type and equate it to the desired terminal. 
This automatically associates certain characteristics of the 
particular terminal type with the specified terminal. (See the 
RSX-11M/M-PLUS 1/o Drivers Reference Manual for a list of the 


implicit characteristics for each terminal type.) The command is 
in the format: 


SET /term-type=ttnn: 


where term-type is one of the standard terminal types. Note that 
the terminal types are mutually exclusive. 


The half-duplex terminal driver also accepts the /term-type form 
of the command. However, the only legal terminal types for the 
half-duplex driver are /ASR33, /LA30S, and /VTO5B. The command 
associates implicit characteristics of the terminal type with the 
specified terminal, but, unlike the full-duplex terminal driver, 
the types are not mutually exclusive. 


The following list describes the effects of the keywords for the 
half-duplex terminal driver: 


/ASR33 Converts lowercase letters to uppercase before 
they are output to the terminal. 
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/LA30S Indicates that fill characters are used after a 
carriage return. The number of fill characters 
used depends on the current carriage position at 
the time the carriage return occurs. 


/VTO5B Sets a vertical fill of three nulls after a line 
feed on 60 Hz systems and of four nulls on 50 Hz 
systems. 


/TOP=pname: value 


Directs VMR to move the top boundary of the specified partition 
up or down the amount indicated by the value parameter. 


The /TOP keyword modifies the top boundary of a system-controlled 
partition even if the partition has tasks installed in it. If 
you modify the partition so that it becomes too small to hold the 
tasks installed in it, VMR displays a warning message but 
modifies the partition anyway. 

pname 

The 1- to 6-character alphanumeric partition name. 

value 


The number of 64-byte blocks. 


The value can be supplied in five formats: +value, -value, 
value, +* or *, and -*. These are described as follows: 


+value 


Moves the partition's top boundary up by the’ specified 
amount. Moving the partition's top boundary up makes 
the partition larger. 


NOTE 


You must supply the value in the same units as 
the base and size parameters for the /PAR 
keyword. 


-value 


Moves the partition's top boundary down by the 
specified amount. Moving the partition's top boundary 
down makes the partition smaller. 


value 


Moves”~ the partition's top boundary until the 
partition's total size is equal to the specified value. 


+£* or * 


Moves the partition's top boundary up as far as 
possible. The most the top boundary can move up is to 
the bottom boundary of the partition above it, or, to 
the top of memory, if the partition is the last 
partition in memory. 
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Moves the partition's top boundary down as far as 
possible. The most the top boundary can move down is 
to the top of the of the first fixed task, common, or 
driver in the partition at the time the /TOP keyword is 
executed. If nothing is loaded into the partition, the 
partition assumes a size of one 64-byte block. 


/TTSYNC[L=ttnn: ] 


(Full-duplex terminal driver only.) Enables the terminal 
synchronization option for the specified terminal. This means 
that the system responds to the CTRL/S and CTRL/Q characters used 
to control the flow of information on the terminal screen, when 
you type them on the terminal. /TTSYNC is the default. 


When you omit the terminal specification, VMR displays all the 
terminals that have terminal synchronization. 


/NOTTSYNC[=ttnn: J 


(Full-duplex terminal driver only.) Disables the terminal 
synchronization option for the specified terminal. The system 
will not respond to the CTRL/S and CTRL/Q characters when you 
type them on the terminal. 


Note that if you set your terminal to /NOTTSYNC, the NO SCROLL 
key on VT100-series terminals and the HOLD SCREEN key on 
VT200-series terminals, will no longer work. 


When you omit the terminal specification, VMR displays all the 
terminals that do not have terminal synchronization. 


/TYPEAHEAD[=ttnn:[size]] 


(Full-duplex terminal driver only.) Enables the typeahead option 
for the specified terminal. 


The terminal driver stores input characters in the typeahead 
buffer before passing them to the task. When the typeahead 
option is enabled, characters input during periods between 
requests are not lost. 


If size is specified (RSX-11M-PLUS systems that support kernel 
data space only), the typeahead buffer size is set accordingly. 
The value for size can be from 0 through 255(decimal). If you 
specify 0 or 1, the terminal will not have the typeahead option 
enabled (same effect as /NOTYPEAHEAD). The default for size is 
86(decimal). 


When you omit the terminal specification, VMR displays all the 
terminals that have the typeahead option enabled. 
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/NOTYPEAHEAD[=ttnn: ] 


(Full-duplex terminal driver only.) Disables the typeahead option 
for the specified terminal. The terminal driver does not store 
characters to prevent their loss because the size of the buffer 
is forced to l. 


When you omit the terminal specification, VMR displays all the 
terminals that do not have the typeahead option enabled. 


/uIc=[Luic]: Jttnn: 


Establishes the specified UIC as the default UIC for the 
specified terminal (the default is TI:). All tasks run from the 
terminal are run with the UIC of the terminal, except in a 
multiuser protection system. In such a system, a privileged user 
can override the terminal UIC with the /UIC keyword of the RUN 
command. 


External MCR function tasks are requested with the /UIC keyword. 
These tasks are the MOUNT, INSTALL, DMO, and UFD commands (which 
execute as tasks), and all system-supplied software. 


When you specify only the terminal, VMR displays the UIC for that 
terminal. 


/VFILL[=ttnn: ] 
(Full-duplex terminal driver only.) Enables the vertical fill 
characters option for the specified terminal. The terminal 


driver adds four fill characters following each line feed. 


When you omit the terminal specification, VMR displays all the 
terminals on the system that have the VFILL option enabled. 


/NOVFILL[=ttnn: J] 


(Full-duplex terminal driver only.) Disables the vertical fill 


characters option for the specified terminal. The terminal 
driver does not add any vertical fill characters following line 
feeds. 


When you omit the terminal specification, VMR displays all the 
terminals on the system that do not have the VFILL option 
enabled. 


/WCHK[=ddnn: J 


Specifies for all Files-1l devices, except DX:, DY:, and magnetic 
tapes, that all write operations are to be followed by a 
write-check. The checks assure the reliability of data transfers 
to the specified disk. 


On RSX-11M, Executive support for write-checking is a system 
generation option and must be selected for this command to cet 
any effect. On TN ne SEpPOre for- eis meee 
always” included. ee 
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When you omit the device specification, VMR displays all Files-1l 
disk drives with write-checking enabled. 


/NOWCHK[=dadnn: ] 


Specifies that write-checking is to be disabled for the specified 
device. 


When you omit the device specification, VMR displays all disks 
that support write-checking but have the option disabled. 


/WRAP[=ttnn: ] 


(Full-duplex terminal driver only.) Enables the wraparound option 
for the specified terminal. The terminal driver automatically 
generates a carriage return/line feed sequence when the number of 
input characters exceeds the buffer size of the specified 
terminal. Both the carriage return and line feed are transparent 
and do not appear in the input buffer. 


When you omit the terminal specification, VMR displays all the 
terminals on the system that have the wraparound option enabled. 


/NOWRAP[=ttnn:] 


(Full-duplex terminal driver only.) Disables the wraparound 


option for the specified terminal. The terminal driver does not 
accept input characters beyond the input buffer size for the 
terminal. 


When you omit the terminal specification, VMR displays all the 
terminals on the system that have the wraparound option disabled. 


Notes on Memory Allocation Keywords 


1. If a command attempts to eliminate a partition in which tasks 
are installed or drivers loaded, VMR rejects the command 
until the tasks have been removed. 


2. When you define a partition, the name must not already be 
defined as a partition. In addition, a partition cannot 
overlap any other partition. 


On RSX-11M, subpartitions can overlap other subpartitions. 


3. The address specified with the /POOL keyword must be lower 
than the base address of the first partition in the system. 


On RSX-11M, an exception is the partition LDRPAR for a 
resident loader. LDRPAR is in the Executive. 


4. Once you have allocated space to the dynamic storage region 
(pool), you cannot recover the space for use in partitions. 


5. When the highest memory addresses of a system are allocated, 
the size of the partition is modified automatically to 
reflect the amount of memory present when the system is 
bootstrapped. 
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. On RSX-11M-PLUS, SET ‘/T0P and SET /30T can ‘be used for 
_ secondary pool partitions. 


If the last partition is system-controlled, its i address 
is modified by the SAVE command at boot time to reflect the 
actual top of physical memory of the hardware in use. 


VMRESET /ABAUN=TT4$ 

Enables the autobaud detection option for TT4:. 
VMR=SET a 

ARAUD=TT 2 

ABAUD= Ta! 

ABAUDS=TTS: 


Displays all the terminals that have the autobaud detection 
option enabled. 


VMRESET /AVOHTT223 


Informs the system that the VT100 terminal TT22: has’ the 
advanced video option. 


VMRSESET /BLAMOD=TTS 


Enables local editing and block-mode transmission for the 
terminal TT3:. 


VMR=SET /BRO=TTS! 

Enables the broadcast option for TT5:. 
YVMR=SET /BRO 

BRO=TT23 

BERO=TT43 

BRO=TTS? 


Displays all the terminals that have the broadcast option 
enabled. 


VMR>SET /BUFELFOS 
BUFFELPOL 132, 


Displays the current buffer size of LPO:. 
VMR=SET /RUF=TT1°40. 

Sets the buffer size of TTl1: to 40(decimal). 
VMR=SET /CRTH=TTS3 


Enables the backwards deletion option on the display terminal 
whose number is TT3:. 
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10. 


ll. 


12. 


13. 


14. 


15. 


16. 


17. 


18. 


19. 


20. 


VMR>SET /CRT 
CRT=TT3! 
CRTSTT7! 
CRT=TT123 


Displays all the terminals that have the backwards deletion 
option enabled. 


VMR=SET /NODEC=TT103 


Informs the system that terminal TTLOs is not 
upward-compatible with the vT100-series of terminals. 


YMRESET /EDVITHTT25: 


Informs the system that terminal Tr25% can perform 
ANSI-defined advanced editing functions. 


VMS=SET /ESCSEQ=TT33 


Establishes terminal TT3: as a terminal that can send and 
receive escape sequences. 


VMR=SET /ESCSEQ 
ESCSEQ=TT33 
ESUSEQ®TT? 3 
ESCSEQSTT1I6$ 


Displays all the terminals that can send and receive escape 
sequences. 


VMRESET /NOESCSEQ=TT3? 

Disables support of escape sequences for TT3:. 

VMR2SET /HSYNCHTT223 

Enables host-terminal synchronization for terminal TT22:. 
VMR=SET /LASOS=TT2% 

VMR=SET /LAZOS 

LA3SOS=TTO? 


LAZOS=TT23 


Sets fTT2: as an LA30S, then displays all the LA30S 
terminals. 


VMRESET /NETUIC 
NETUTCH=£20931 


Displays the current network UIC. 
VAR=SET /NETUTCHEC25 96) 

Sets the network UIC to [25,6]. 
VMR>SET /OPT=0M1SNEAR 


Enables I/O queue optimization for DMl:, using the NEAR 
algorithm. 
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 OPT=DBLSNEAR 


 OFT=EMOINEAR 
OPT=DM1{NEAR 


optimization enabled. 


22. 


23. 


24. 


25. 


26. 


27. 


28. 


29. 


30. 


VMRoSET /FARITY=TTLISSEVEN 


Enables parity generation and checking for terminal TT15: 
and informs the system that if an even number of bits are 
counted during data transmission, the transmission of data 
does not return an error. 


VMRSSET /FASTHRUHTT 223 


Informs the system that it should ignore special characters 
typed at terminal TT22: and pass them to a program in their 
binary form. 


VMROSET /PLCTL 
PLOTL=14600.3600.3200.+51. 


Displays the current pool limit parameters used by the Pool 
Monitor Task. 


VMRESET /PRINTERUFORT=TT22% 

Informs the system that TT22: has a printer port. 
VMRESSET /FRIV=TTO3 

Sets TTO: to be a privileged terminal. 


VMRESET /FRIV 
FRIV=TTO? 
PRIVeETTILs 


Displays all privileged terminals. 
YMRESET /REGIS=TT1IS: 


Informs the system that the terminal TT15: supports the 
ReGIS graphic set. 


VMR=SET /REMOTE=TT21 3 


Sets the terminal line corresponding to TT21: as a remote 
dial-up line. 


VMROSET /REMOTE 
REMOTE=TTI 3 
REMOTE=TYT2 3 
REMOTE=TT3; 
REMOTE=TT 4? 
REMOTE=TT213 


Displays all the terminals that are currently set as remote 
dial-up lines. 
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31. 


32. 


33. 


34. 


35. 


36. 


icy a 


38. 


39. 


40. 


41. 


42. 


VMRESET /RNIC 
RNICH6, 


Displays the current length of the round-robin’ scheduling 
interval. 


YMR=SET /RNTICH=1L0, 


Sets the length of the round-robin scheduling interval to 
10(decimal) ticks. : 


VMR>SET /SECPOL 
SECPHL=285.26403 44% 


Displays the amount of secondary pool currently being used. 
VMRSSET /SLAVE=TTS¢ 

Sets TT3: to be a slaved terminal. 

VMRESET /SOFTH=TT223 


Informs the system that terminal TT22: accepts 
software-defined character sets. 


VMRGSET /SWPR 
SWFR=S. 


Displays the current value for the Executive swapping 
priority range. 


VMR=SET /SWFR=10. 
Sets the Executive swapping priority range to 10(decimal). 


VMR=SET /TERM=TT253 
Term=TT253 VT100 


Displays the terminal type of terminal TT25:. 
VMRESET /TERM=TT25SVT2AXX 


Requests the system to give terminal fMTT25: the same 
capabilities as a VT200-series terminal. 


YMR=SFET /TISYNCHTT22 3 

Enables terminal synchronization for TT22: 
VMR=SET /VTOSB 

YTOSBR=TT43 

VTOSR=TTS? 

VTOSR=TT63 

Displays all VTO5B terminals. 

VMR=SET /WCOHK=TIR1G ¢ 


Enables write-checking on DKI1:. 
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VMRSSET /FPOOL=420 


Establishes the top of the dynamic storage region (pool). 
Following this command, no user-defined partition can begin 
below 42000(octal). 


VMRSSET /POOL 
POOL =1200311470.511738.32003 


Shows that the last virtual address in the Executive is 
120000, the longest free block is 11470(decimal)-words, and 
the total of all pool space is 11738(decimal)-words. The 
lowest physical address at which a partition can start is 
2003 (32-word blocks). 
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Use the TASKLIST command to display a description of each installed 
task in the system. The display contains several columns that give, 
from left .xp TASKLIST command (VMR)display contents to right, the 
following information: 

@e Task name 

e Task version identification 

e Task Control Block address 

@e Partition name 

e Task priority 

e Size of task in bytes (in octal) 

@e Load device identification 

e Disk address logical block number (in octal) on unsaved 

systems, or the image or task file identification on saved 


systems 


@ Task memory state (saved systems only) 


On RSX-11M=<PLUS, the display lists t asks installed in primary pool 
and then the tasks installed i secondary pool. The tasks in 
secondary pool are indicated by a plus sign (+). 


Format 
TAS[KLIST][taskname] 

Parameter 

taskname 


The name of a single installed task, whose description you want 
displayed. 


Examples 


1. The following example is from an unsaved system: 


VMR= TAS 

TRTN 03.14 035300 GEN 248, 010000 LEO? -004631420 
oe MOR 01.01 035174 GEN 140. 040000 L.B03-00630300 
MCR... 3.43 035070 GEN 140, 010000 LRO3-00627721 
e+e INS 4 0354614 GEN 100. 040000 1B0$-004627333 
++ el OA 03.3 035510 GEN 30. 040000 LRO$-00627643 
oe UNL 03.4 035404 GEN 29+ 040000 LRO?-00070512 
VMR > 


On a system image generated for a 22-bit system with more 
than 124K-words of memory, the size field (sixth column) 
contains 8-digit rather than 6-digit numbers. 
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2. The following example is from a saved system: 


VNR: TAS 

LOR... 08,03 034210 LORFAR 248. 00003000 LRO{- FILE IMS (tLiisi2) FIXED 
TKTN 03.14 115424 GEN 248. 00010000 LROt- FILE 103031540927) 
MTAACF 0010 115214 GEN 200. 00013500 LROS- FILE Ins (31461224) 
MCR.+. 3.3 1146464 SYSPAR 160. 00010000 LBOS- FILE T03¢31454s12) 
oo DCL O113A 115634 GEN 160. 00040000 LBOS- FILE J0$ (31344953) 
DClieses OLLSA 115530 GEN 1460, 00010000 LROS- FILE 10%(°3134595) 
e+ eMCR O1.01 036770 GEN 160. 00040000 LROS- FILE 303630544134) 
eee MOU 23.00 034250 GEN 140, 00040000 LBOS- FILE 1023¢5424915) 
Fi1ACF M0320 117674 GEN 149. 00065700 LBO?- FILE I$¢30101247) 
DROOFL M0320 117570 GEN 149. 00065700 LBOt- FILE TU (31370746) 
COT... XO0.01 117340 GEN 145. 00015400 LRO?{- FILE 103 (313362120) 
oo DMO 23.00 117254 GEN 140. 00040000 LBOt- FILE 1086313446723) 
eee INT 20.01 116674 GEN 140. 00040000 LRO{- FILE TUS (314249505) 
oe UFO YO410 114044 GEN 140. 00040000 LBOt- FILE TU3¢031541934) 
PMIl..+ 361 114630 GEN 140. 00023600 LBOt- FILE I03 (3146470) 
HROwee O1L-OL 0346560 GEN 140. 00050400 LBOt- FILE 103031240721) 
SHFs++ 93.01 115320 SYSFAR 105, 00010000 LROt- FILE 33 (31571240) 
FXRees O1 117104 GEN 100. 00003100 LBOt- FILE 10$¢313717113) 
eee INS 4 114570 GEN 100. 00027700 LBO?- FILE IMs (3143512) 
1+ SAV 04.35 1146254 TSTPAR 100, 00040000 LBOt~- FILE 10803147595) 
SAVTO 04.35 036130 TSTFAR 100. 00040000 LROS- FILE I0¢¢3147595) 
oo eFRY 4,30 0364464 GEN 100. 00040000 LBOt- FILE 1036343391463) 
eee ATs 04,425 037254 GEN 65. 00057700 LROi- FILE T02(¢314217131) 
++ +BOO 04.08 1174464 GEN 30. 00040000 LBOS- FILE T08¢3132376) 
+etACS O1.1 115740 GEN 10. 00040000 LROt- FILE 103¢31321973) 
e+ tHEL 01.25 037360 GEN 50. 00044100 LBOS- FILE Thi¢3t4t6915) 
YMR > 


The display for a saved system differs from the display for a 
unsaved system in that the file-ID of the task file, rather 
than the logical block number, is displayed. FIXED indicates 
that the task is fixed in memory. 


3. The following example is : 11M-PLUS saved system 


that has tasks onetaties secon pool: — 
UHR TAS 
a. — oe ee ae 
BAFO 02 #113440 GEN 80. 00045700 LBOi- FILE ID! (433292 7) 
QMG... 14.7 412450 GEN $75, 00031400 LBOt- FILE 103(4346,2) — 
‘1.9 $(112734 GEN  =$70. 60015400 LROS- FILE 103(4354,135) — 
4.9 112604 GEN 70. 00015400 LBOi- FILE 1D! (43545135) 
++ 01.01  ##$110600 GEN 60. 00051700 LBOS- FILE IN$¢(43460+2) 
T'UP O02 =————is410320 «GEN =—s- $0. 00011200 LBO?- FILE ID$(432 65) 
oe et GEN 160, 00015500 LROt- FILE 19!¢4167.35) 
2.4 0060374 GEN 140, 00032000 LBOt- FILE 103 (2132 9227) 
, 2502 (006041+ GEN 160. 00040000 LRO!t- FILE ID$ (4205713) 


BcL 00° 9061304 GEN = 140. 00035400 LBOi- FILE 103 (25: 


+ 


 UMRS 
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TIME 

Use the TIME command to set the date and time or to display the date 
and time. The TIME command has two formats. 

Format 1 


TIMCE] Chrs:mins[:secs]] [ml/day/year] 
Format 2 

TIM[CE] C[hrs:mins[:secs]] [day-m2-year] 
Parameters 
hrs 


Hours (range O through 23). 


mins 
Minutes (range O through 59). 
secs 
Seconds (range 0 through 59). This parameter is optional; the 
default is zero. 
ml 
Numeric representation of month (range 1 through 12). 
m2 
Three-letter abbreviation for month. 
day 
Day (range 1 through 31). 
year 
Year (range 0 through 99). The year is relative to 1900; 
therefore, 1986 is entered as 86. 
Examples 


1. VMROTIM 
10323331 21-JUN-85 


Displays the current system image time and date. 
2. VMAS TIM 14330 6724/85 


Sets the time to 14:30:00 and the date to 24-JUN-85. 
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You can specify the time and date in any order. 


If you specify the time and the date, VMR sets the system 
image clock and calendar. 


If you specify the time but not the date, VMR only sets’ the 
clock. 


If you specify the date but not the time, VMR only sets’ the 
calendar. 


If you don't specify a time. or date, VMR displays the current 
system image time and date. 


The form used to specify the date does not affect the display 
format. The date is always displayed as day-month-year. 


All numeric values are decimal. No terminating period (.) is 
required. 
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UNF 


UNFIX 

Use the UNFIX command to free a fixed task from the virtual memory of 
the system image. The UNFIX command is the complement of the FIX 
command. 


If a fixed task exits or aborts, it still occupies the physical memory 
in the partition. 


Format 
UNF[IX] taskname[ /keyword] 
Parameters | 
taskname 
The task that you want to unfix from memory. 
/keyword 


One of the following (RSX-11M-PLUS systems only): 


/REG 
/RON 
Keywords 
/ REG 
Specifies that the task to be unfixed is a common region. 
oe Re | ae 
Specifies that the task ie ‘Apuleius task, the read-only 
segment of which is to be unfixed from memory. 
Example _ 


VMROUNFIX XKE 


Unfixes task XKE, freeing the partition in which it resides. 
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UNLOAD 

Use the UNLOAD command to remove a loadable device driver from the 
system image. If a device is attached however, its driver cannot be 
unloaded. 


To unload a device driver from the system image, the driver's symbol 
definition file must reside on LB: under the same directory as the 
directory of the system image file. The system directory is usually 
[1,50] for an unmapped system and [1,54] for a mapped system. 


The UNLOAD command cannot remove a loadable data base from the system 
image, even if the data base was loaded by means of the LOAD command. 


Format 
UNL[OAD] dd:[/VEC] 
Parameters 
dd: 
A 2-character ASCII device name. You must specify a device name. 


/VEC 


“(errs systems on 
to be unloaded is v 
comparison of the drive 


he system that the driver 
> /VEC keyword prevents the 
file and the system symbol 


table file. 
Example 
YAREUNL LPS 


Unloads the line printer driver (LPDRV). 
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10.6 VMR ERROR MESSAGES 


This section contains explanations for VMR error messages. Error 
messages can appear in one of the following formats: 


The 


VMR -- *DIAG* message 


This format indicates a diagnostic error message. A diagnostic 
error message usually indicates that something unexpected 
happened, but that the error did not interfere with VMR's 
operation. 


VMR -- message 


This is an unmarked error message. An unmarked error message 
usually indicates that VMR_ rejected the command line. If the 
offending line is in an indirect command file, VMR ignores’ the 
rejected line and attempts to execute the remaining command 
lines. 


VMR -- *FATAL* message 


This is a fatal error message. A fatal error message indicates 
that VMR rejected the command line and that VMR has either exited 
or reset itself to the beginning (that is, Enter filename:). 1G 
the offending line is in an indirect command file, VMR exits 
without attempting to execute the remaining command lines. 


following explanations for error messages contain the text of the 


error message, but not the format. They are in alphabetical order. 


VMR 


VMR 


VMR 


VMR 


VMR 


VMR 


-- Access to common block denied 


Explanation: You attempted to install a task that has specified 
illegal access to a shared region. 


-- Addressing extensions not supported 

Explanation: You attempted to install a task that was built 
using the VSECT (virtual section) directive into a system image 
that does not support the VSECT feature. 

-~ Alignment error 

Explanation: The base address or size of the partition being 
created with the SET command conflicts with existing partitions 
or physical memory. 


-- Base address must be on a 4K boundary 


Explanation: The virtual base address of the task being 
installed is not aligned on a 4K boundary. 


-- Base mismatch common block <commonname> 


Explanation: The base address of the partition does not match 
that of the common block. 


-- Bus switch not loaded 


Explanation: You attempted to load a device requiring a bus’ run 
before you loaded the bus switch. 
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-- Cannot fix an I/D space task 


Explanation: You attempted to fix a task that is built with I- 
and D-space. These tasks. cannot be fixed. 


-- Cannot fix a task in a system controlled partition 


Explanation: This is a VMR restriction. To fix a task in a 
system-controlled partition, use the MCR FIX command and then 
save the system image. 


-- Cannot have multiple pool or CPU partitions 
Explanation: You attempted to create a secondary pool partition 


in a system that already has one. There can be only one 
secondary pool partition in a system. 


R Cannot. install shared region with increment 


"— mxplanation: You specified - ‘both -/tNc=size and _ /wa=ves heat 


ng a common. -When a common is installed with - 


it will no longer fit in its original task~ image file; 


| epecetea you cannot also specify that the common. De written 
back into its: task image file (/WB=YES) . : 


VMR 


VMR 


VMR - 


-- Cannot install tasks or commons from Stier than LB: 
Explanation: SAVE does not allow saving of a system that has 
tasks and/or commons that were not installed from the library 
device LB:. Therefore, a task or common cannot be installed from 
other than LB:. 

-- Cannot LOAD/UNLOAD a pseudo device 


Explanation: When loading or unloading a device driver, the 
physical name of the driver must be specified. 


-- Cannot UNFIX a mapped common region 


Explanation: You attempted to unfix a common region that is 
currently mapped by a task. 


ote Cannot ‘UNFIX the directive ‘common 


eee tanetion: /RSX-11M-PLUS Airective | commons can be. foes. but 


a not unfixed. Because directive commons are merged with DIR11M as 
they are fixed, the size of a particular common is unknown. 


VMR 


VMR 


-- Checkpoint area too small 


Explanation: The area allocated for checkpointing in the task 
image file is smaller than the partition into which the task is 
being installed. The system image does not support the dynamic 
allocation of checkpoint space. 


-- Checkpoint space too small, using checkpoint file 


Explanation: This is a warning message. The checkpoint space 
allocated in the task image file is too small to hold the task 
(usually because of the /INC keyword). The system image supports 
the dynamic allocation of checkpoint space. It will use the 
checkpoint file to store the task when it rolls it out to disk. 
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-- Circular redirect error 


Explanation: The attempt to redirect a device failed because it 
would result in a circular device list. 


-- Command I/O error 


Explanation: The system detected an I/O error during a read from 
an indirect command file. 


-~- Command syntax error <command-line> 
Explanation: The syntax of the command line is incorrect. 
-- Common block currently installed 


Explanation: You attempted to install a common block that has 
already been installed. 


-- Common block is task partition <commonname> 

Explanation: A task's request for access to a common block has 
been rejected because the requested partition is a task 
partition. 

-- Common block not loaded <commonname> 

Explanation: The common block specified by VMR in the error 
message has been linked to the task, but the common block has not 


yet been installed. 


User Action: The common block must be installed before the task 
can be installed. 


-- Common block occupied 


Explanation: You attempted to install a task in a common block 
that was already occupied. 


-- Common block parameter mismatch <commonname> 

Explanation: The parameters of the common block named in the 
error message do not match the parameters in the label block of 
the task that references the common block. 

-- Common block segment count error 

Explanation: You attempted to install a resident library with 


overlays, but the number of overlay segments in the task header 
differs from the number specified in the segment descriptors. 


-— CTB <name?, does not exist 


explanation: The Controller Table (ors) name that you specified 
with the LOAD /CTB keyword does not exist in the resident data 
base. 


-- CTB name <name> is a duplicate 
Explanation: The loadable data base contains a Controller Table 


with a name that is the same as a CTB name in the resident data 
base. CTB names must be unique. 


10-96 


VIRTUAL MONITOR CONSOLE ROUTINE (VMR) 


ed 
VMR Siepiave this 
“he Driver Dlapecon ‘Table in tha. iver does not have all the 


"Controller Table mnemonics that the rest of the data base 
A(t ns DBs and CTBs) implies that it should have. 


9. ake CTB is defective. A defective CTB may contain a _ wrong 
mame or it may point at the wrong DCB. 


VMR -- Data space file exceeds available space in system image 


Explanation: The RSX11M.SYS file is not large enough to contain 
the data space file DSP11M.TSK. 


table for CTE <name> is full 


VMR -- Device <ddnn:> is at cached 


Explanation: You attempted to unload a driver that has one or 
more of its device units attached. The first attached unit is 


ddnn:. You cannot unload a driver that has device units 
attached. 
VMR -- Device <ddnn:> is not in system 


Explanation: VMR displays this message for any of the following 
reasons: 


1. You attempted to save an image on a device that does not 
exist on the host system. 


2. You attempted to redirect I/O requests to a device that does 
not exist on the host system. 


3. You specified a device in the LOAD command line for which 
there is no data _ base. This is caused by one of two 
conditions: 


a. The device does not exist in the system device tables. 


b. You did not declare the device to be loadable and 
therefore LOAD cannot find a loadable data base for it. 


4. You specified a device in the command line that has not been 
defined in the system image. 


5. You specified a device in the DEVICES command line that does 
not exist in the system image. 


VMR -- Device not mounted 


Explanation: You failed to mount the device that contains the 
system image file. 
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-- Device not redirectable 


Explanation: You attempted to redirect a device that is marked 
(in its UCB) as not redirectable. 


-- Device not terminal 


Explanation: You attempted to set terminal characteristics for a 
device that is not a terminal. 


-- Device not variable speed multiplexer 
Explanation: You attempted to set the speed for a terminal that 
is not attached to a DH11, DHU11, DHV11, DZ11, DZQ11, or DZV11 


multiplexer. 


— Directive common already loaded 


: Explanation: You attempted to fix in the REXEEIM-PLUS system 


image a directive common that is already fixed. 
-- Directive common not contiguous to DIR11M 


Explanation: Directive commons must be loaded contiguous to 
DIRIIM. 


~— Directive common is) not fixed in memory 


‘Explanation: | ‘Not fald: : - the ‘Aireckive commons that were 
installed in the RSX-11M-PLUS system image have been fixed. 


-- Driver already resident 


Explanation: You attempted to load an already loaded device 
driver or one that is permanently resident in the system image. 


-- Driver built with wrong STB file 


Explanation: The symbol definition file for the driver you 
attempted to load or unload is not compatible with the Executive 
symbol definition file for the current system image. This means 
that the driver has been built for another system and must be 
rebuilt before you can load it into the current system. 


-- Driver cannot be unloaded 


Explanation: You attempted to unload a permanently resident 
driver (that is, a driver linked permanently to the Executive). 


-- Driver dispatch table is inconsistent 


Explanation: You attempted to load a driver with an illegally 
formatted driver dispatch table. See the RSX-11M Guide to 
Writing an r/o Driver or the RSX-11M-PLUS Guide to to Writing an 1/0 
Driver for more information. 


-- Driver not loaded 


Explanation: In the UNLOAD command line, you specified a driver 
not resident in memory. 


-- Driver requires running system for LOAD/UNLoad 
Explanation: The driver you requested has the symbols $ddLOA or 


S$ddUNL in its source. Support of driver load/unload calls can be 
provided only by the MCR LOAD/UNLOAD commands. 
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-- Executive common partition eliminated 
Explanation: This is a warning message. One of the Executive 
common partitions has been removed. A system generated with 
Executive common support must have both partitions installed to 
run. 
-- Executive common(s) not installed 
Explanation: This is a warning message. For a system generated 
with Executive common support, you should install one (or both) 
of the commons before you exit VMR. Otherwise, the system is 
unusable. 
-- Executive too large 


Explanation: The Executive is too large to be accommodated in 


the 


system image. This message indicates that the Executive is 


larger than 20K. The system is unusable. 


-- External headers not supported 


Explanation: You attempted to install a task built with external 
headers in a system that was not generated with external header 
support. 


~~ Fast map not BUPPOEEEG 


Explanation: You attempted: to dnetall a tack with Sie. /EMAP=YES 


keyword, without having first selected support for fast mapping 
during system generation. 


-- Feature not supported in system image 


Explanation: VMR displays this message for any of the following 
reasons: 


1. 


2. 


You attempted to create secondary pool in a system that does 
not support it. 


You attempted to set a device public in a system that does 
not support multiuser protection. 


You attempted to enable/disable the broadcast option for a 
terminal, but the system is not a multiuser/multi-CLI system. 


VMR -- File <name> has illegal format 


Explanation: The driver's symbol definition file contains 
illegal object code or data. 


VMR -- File <name> has inconsistent data 


Explanation: This message can occur for the following reasons: 


l. 


2. 


You attempted to fix a partition or a task that is logically 
beyond the end of the system image file. 


The partition for loadable drivers is logically beyond the 
end of the system image file. The system image is probably 
corrupt. 


The partition of the common library you are attempting to 
load is logically beyond the end of the system image file. 
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VMR -- File <name> not a valid driver task image 


Explanation: One of three things has occurred: 


l. The driver's task image has been overlaid. 

2. The driver has a header. 

3. The driver has referenced a resident library. 
VMR -- File not contiguous 


Explanation: This message can occur for the following reasons: 


1. You attempted to install a task from a noncontiguous file. 
Task images must reside on contiguous files. 


2. The file ddDRV.TSK is not contiguous. This file must be 
contiguous for a device driver to be loaded. 


VMR -- File not found 


Explanation: You requested a file not located in the directory 
of the volume you specified. 


VMR -- File not task image 


Explanation: The data in the label block of the task you tried 
to install is incorrect, indicating that the file is not a task 
image. 


VMR -- Illegal device/volume 


Explanation: You attempted to save your system image on an 
invalid device. Valid devices are: 


CT: Tape cassette 

DD: TU58 DECtape II 

DT: DECtape 

DU: RX50 diskette/RA60 disk/RC25 disk (removable) 
DX: RXOl1 diskette 

DY: RXO2 diskette 

MM: TE/TU16/TU45/TU77 magnetic tape 

MS: TS11/TSVO5/TU80 magnetic tape 

MT: TE/TU1LO/TSO3 magnetic tape 

MU: TK50 cartridge tape/TU81 magnetic tape 
PP: Paper tape 


VMR -- Illegal driver task APR usage 


Explanation: The device driver being loaded must be built for 
APR 5 and must be less than 4K-words. 


VMR -- Illegal error severity code <code> 
Explanation: This message indicates an internal failure in VMR. 
If this error message persists, contact a DIGITAL software 
representative. 


VMR -- Illegal file specification <filespec> 


Explanation: The file specification printed following the error 
message has an illegal format or contains wildcards. 
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-- Illegal first APR 


Explanation: The task you tried to install was built using an 
incorrect base APR. The following rules apply: 


1. A nonprivileged task must be built with APR O as its base 
APR. 


2. A privileged task that does not map into the Executive must 
be built with APR O as its base APR. 


3. If the Executive is 16K-words or less, a privileged task that 
is to map to the Executive routines and data structures must 
be built with APR 4 as its base APR. 


4. If the Executive is 20K-words, (or less on RSX-11M-PLUS 


systems), a privileged task that is to map to the Executive 
routines and data structures must be built with APR 5 as its 
base APR. 


-- Illegal function 

Explanation: You entered a command that VMR does not recognize, 
or the command line refers to a feature that is not supported in 
the system. 


-- Illegal Get Command Line <error code> 


Explanation: This message indicates a system failure. If the 
error persists, contact a DIGITAL software representative. 


-- Illegal keyword value 


Explanation: You entered a value for a keyword that is out of 
range. 


-- Illegal operation for unmapped system 


Explanation: The SET /POOLSIZE keyword is valid only on mapped 
systems. 


-- Illegal parameter for executive common partition 

Explanation: You specified a parameter with SET /MAIN that is 
illegal for an Executive common. The partition size must be 
200(octal) and the partition type must be COM. 

-- Illegal priority 

Explanation: You specified an illegal priority for the task. A 
priority value can be a number from 1 to 250. 250 is the highest 
priority and 1 is the lowest priority you can assign. A priority 
is assumed to be octal unless you put a period (.) after the 
priority number. 
-- Illegal slave attribute 

Explanation: You attempted to install a task with the /SLV 
keyword, but the task's name is in the form ...xxx. The task is 
a prototype task and cannot be installed as a slaved task. 


-~- Illegal switch <switch> 


Explanation: The switch following the error message is incorrect 
in the context of the command line you have entered. 
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-- Illegal use of <pname> partition or common 


Explanation: You attempted to install a task in a CPU or 
secondary pool partition. 


-- Illegal use of <pname> partition or region 


Explanation: You attempted to load a driver into a common or 
secondary pool partition. 


-- Illegal use of wildcard 


Explanation: On an unmapped system, you cannot’ specify a 
wildcard (*) with the following SET keywords: /TOP, /BOT, and 
/POOL. You also cannot use a wildcard for the size parameter of 
task partitions. 


-- Illegal value for symbol <symname> in file <filename> 
Explanation: LOAD or UNLOAD has determined that symbol <symname> 
in the STB <filename> has been defined to an illegal value. This 
can occur for several reasons, some general and some specific to 
individual symbols. For example, most symbols generally cannot 
be defined to zero or to an odd number. A _ specific example is 
the symbol SINTSV, which must not be referenced by mapped 
loadable drivers. 

-- Incorrect assignment of SY: or LB: 

Explanation: This is a warning message. The device SY: or LB: 
is not assigned to the same device as the system image file you 
are trying to work with in VMR. 

-- Indirect command syntax error <command-line> 


Explanation: You entered an improper indirect command file 
specification. 


-- Indirect file depth exceeded <command-line> 


Explanation: You attempted to reference more than two levels of 
indirect command files. 


-- Indirect file open failure <command-line> 


Explanation: The indirect command file specified in the command 
line could not be opened. 


-~- Install device not LBO: 


Explanation: You attempted to install a task from other than the 
boot device. 


-- Installed tasks or commons may no longer fit in partition 
Explanation: This is a warning message. You shortened a 
partition so that the tasks and/or commons that are installed in 
it may no longer fit. VMR shortens the partition even though 
this situation exists. 

-- Interrupt vector already in use 
Explanation: The interrupt vector for the driver being loaded 


does not point to one of the nonsense interrupt entry points in 
the system image. 
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-- Invalid driver data base at offset xxxx in file <filename> 
Explanation: The driver name has an invalid data base value at 
offset xxxx relative to the symbol $ddDAT. (See the RSX-11M 
Guide to Writing an I/O Driver or the RSX-11M-PLUS Guide to 
Writing an I/O Driver.) 

-- Invalid interrupt vector 


Explanation: You specified an interrupt vector address in the 
driver data base that is too high for the system image. 


-~- Invalid keyword 


Explanation: You specified a keyword that is incorrect in the 
context of the command. 


-- Invalid record address for file <filename> 

Explanation: LOAD has attempted to write outside of the system 
image file or at a byte boundary. Three possible causes are as 
follows: 

1. A corrupted system image 

2. An STB file that does not match the system image 

3. An internal problem in VMR 


-- Invalid speed 


Explanation: VMR displays this message for either of the 
following reasons: 


1. You requested a speed that the multiplexer line you specified 
does not support. 


2. You specified unequal receive and transmit speeds for a DZ1l, 
DZQl11, or DZV11l multiplexer. These multiplexers do not 
support split speeds. 


-- Invalid time parameter 


Explanation: The time field you specified in the RUN command 
line is incorrect. 


-- Invalid UIC 

Explanation: You specified an illegal value for either a group 
number or a member number. The numbers must be from 1 through 
377(octal). 

-- I/O error on input file <filename> 

Explanation: An input I/O error occurred on the indicated file. 


-- I/O error on output device 


Explanation: SAVE has encountered an I/O error on the output 
device while writing the system image. 


-- I/O error on output file <filename> 


Explanation: An output I/O error occurred on the indicated file. 
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VMR -- Keyword not supported for this terminal driver 


Explanation: The terminal driver selected during system 
generation does not support the specified SET keyword. For 
example, typeahead is a full-duplex terminal driver option only 
and your system uses the half-duplex driver. 


VMR -- KRB <KRBname> interrupt vector <octal-number> in use 


Explanation: You attempted to load a driver that specifies an 
interrupt vector that is not pointing to a nonsense interrupt 
entry point address. This is usually caused by a= previously 
loaded driver that has used this vector. 


When you get this message, LOAD has loaded the driver correctly, 
but it has not overwritten the interrupt vector. 


VMR -- KRB <KRBname> interrupt vector <octal-number> too high 
Explanation: You attempted to load a driver that specifies an 
interrupt vector address that is higher than the highest 


permissible vector address in the system. 


When you get this message, LOAD has loaded the driver correctly, 
but it has not overwritten the interrupt vector. 


VMR -- KRB <KRBname> not in loadable data base 
Explanation: You attempted to load the driver for a 
multicontroller device with a loadable data base. The special 
symbol (KRBname) that defines the location of the KRB in the 


multicontroller device's CTB table is not defined in the loadable 
data base. See the RSX-11M-PLUS Guide to Writing an I/O Driver. 


VMR -- KRB table of CTB <CTBname> will not accept KRB <KRBname> 


Explanation: You attempted to load the driver for a 


multicontroller device with a loadable data base. If this 
operation is to succeed, then the following conditions must 
exist: 


1. The appropriate slot in the CTB must exist. 
2. The slot in the CTB must be unused. 


When VMR issues this error message, one of these conditions does 
not exist. See the RSX-11M-PLUS Guide to Writing an I/O Driver. 


VMR -- Length mismatch common block <blockname> 


Explanation: The length parameter for the common block, as 
described in the label block for the task image, does not match 
the corresponding length parameter defined in the system image. 
A task's label block data must match system data for that task 
before it can be installed. 


VMR -- Line not DZ11 
Explanation: You attempted to set a line to remote that is not 


attached to a DZll, but your system uses the half-duplex terminal 
driver. 
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-- Loadable driver larger than 4K 


Explanation: This is a warning message. You are loading a 
driver that is larger than 4K-words. 


-- Loadable driver support not in system 


Explanation: You attempted to load a device into a system image 
that does not contain the Executive routine SINTSI. The routine 
is needed to support loadable device drivers. 


-- Logical device not in system 


Explanation: The device you specified has not been defined and 
therefore ASSIGN could not find it in the logical device 
assignment table. 


-- LUN out of range 


Explanation: You attempted to reassign a LUN for a task that is 
higher than the maximum number of LUNs allocated for the task 
when it was built. 


-- No checkpoint space, assuming not checkpointable 


Explanation: This is a warning message. You attempted to 
install a task as checkpointable that was not built as 
checkpointable. This means that there is no checkpoint space 
allocated in the task image file. Since the system image does 
not support the dynamic allocation of checkpoint space, INSTALL 
does not consider the task to be checkpointable. 


-- No checkpoint space or dynamic checkpoint file 

Explanation: You attempted to install a task built with external 
headers or as_checkpointable, but the task does not have any 
checkpoint space and the system does not have a checkpoint file. 


-- No ICB pool space for CPU <cpu> 


Explanation: The Interrupt Control Block (ICB) pool space 
allocated for CPU <cpu> has been exhausted. 


~- No LUNs 

Explanation: The task that you specified as an argument of the 
LUN command does not have any logical units assigned to it. This 
is not an error message; rather, it is simply an indication that 
there are no assignments to display. 


-- No pool space 


Explanation: The pool space required to load the driver is not 
available in the system image. 


-- No room available in STD for new task 
Explanation: There is no dynamic storage available to make an 


entry in the System Task Directory (STD). The task cannot be 
installed. 
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VMR -~ No table space for optional directive common 


Explanation: You attempted to fix a directive common in the 
RSX-11M-PLUS system image, but the extra slots built into the 
system data base for optional directive commons have all been 


VMR -- Nonexistent memory 


Explanation: You attempted to define a partition in nonexistent 
memory. 


VMR -- Not enough APRs for task image 


Explanation: The Task Builder allows you to specify, as a 
multiple of 4K, the virtual base address of a task image. 
Privileged tasks that access the Executive start at either 
virtual address 100000(octal) for a 16K Executive or at virtual 
address 120000(octal) for a 20K Executive. If the virtual base 
address of the task is set too high, there are not enough APRs 


remaining to map the task image. (See the RSX-11M/M-PLUS' and 
Micro/RSX Task Builder Manual for information on privileged 
tasks. 

VMR -- Old device attached 


Explanation: You attempted to redirect an attached device. 
VMR -- Open failure on file <filename> 

Explanation: The indicated file cannot be opened. 
VMR -- Operation cannot extend above first 124K of memory 


Explanation: VMR displays this message for either of the 
following reasons: 


1. On RSX-11M, you attempted to fix a task above 124K-words. 
The largest system that can be saved is 124K-words. If FIX 
allowed you to fix a task above this limit, the task would be 
lost when the system was saved. 


2. You attempted to create with the SET command a CPU partition 
whose upper limit is above 124K-words. 


VMR -- Operation not allowed for <ptype> partitions 


Explanation: You attempted a SET operation that is not allowed 
for the type of partition specified in the error message. 


£ 

VMR -- Optional directive common successfully loaded 
Explanation: This is an informational message. VMR has 
successfully fixed in the system image a directive common that is 
not one of the commons required by RSX-11M-PLUS. 

VMR -- Partition already exists 


Explanation: VMR displays this message for either of the 
following reasons: 


1. You attempted to define a partition, using the SET command, 
with a name already in use as a partition name. 


2. You attempted to define a subpartition, using the SET 
command, but there are no more subpartition slots available. 
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VMR -- Partition or common region is busy 


Explanation: VMR displays this message for any of the following 


reasons: 


1. You attempted to fix a task or common region in a partition 


that is full. The task or region cannot be fixed. 


2. You attempted to load a device driver into a partition, 
the partition is full. 


but 


3. You attempted to remove a partition that still has tasks 


installed in it. The partition cannot be removed. 


4. (RSX-11M-PLUS systems only.) You attempted to remove a region 


that is referenced by tasks installed in the system. 


VMR -- Partition <pname> is a common 


Explanation: You attempted to load a device driver into a common 


partition. This cannot be done. 


VMR -- Partition <pname> is not a common 


Explanation: Partition <pname> was found, but it is not a common 


partition. 


VMR -- Partition <pname> is too small 


Explanation: You attempted to load the driver into a partition 


that is either too small for the driver or that does 


not 


currently have enough space for the driver. Or, you attempted to 


install a task that is too large for the specified partition. 
VMR -- Partition <pname> not in system 


Explanation: VMR displays this message for either of 
following reasons: 


1. The partition you specified in the command line is not in 
system image. 


2. You attempted to load a driver into a partition that does 
exist in the system, or LOAD found a symbol $xxCOM in 
driver and partition xxCOM does not exist in the system. 

VMR -- Partition <pname> not in system, defaulting to GEN 

Explanation: This is a warning message. You attempted 

install a task in a partition that does not exist. VMR will 

to install the task in the partition GEN. 


VMR -- Partition not system controlled 


the 


the 


not 


the 


to 
try 


Explanation: The SET command keywords /TOP and /BOT are valid 


only for system-controlled partitions. 
VMR -- Partition reduced to executive fommon size 


Explanation: This is an informational message. When 


an 


Executive common is installed in its partition, the partition is 
reduced to the top of the common to eliminate any unused space in 


the partition. 
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-- Pool link error at xxxx Block=yyyy zzzz 


Explanation: When SET /POOL traced the pool linkage, it detected 
an error at location xxxx in the system image. The contents of 
XXXX is yyyy and the contents of xxxx+2 is zzzz. 


-- Privileged task overmaps I/O page 


Explanation: This is a warning message. A privileged task that 
may need access to the I/O page does not have that access. 


A privileged task that is mapped to the Executive is often mapped 
to the I/O page as well. However, many privileged tasks do not 
require access to the I/O page and can use the extra 4K of 
address space that would be allocated to the I/O page for the 
task image. 


If the task does not require access to the I/O page, you can 
ignore this message. 


-~- Privileged task larger than 12K 


Explanation: You attempted to install a privileged task that is 
larger than 12K-words. (See the RSX-11M/M-PLUS and Micro/RSX 
Task Builder Manual for information on privileged tasks. 


~~ Pseudo device assignment error 


Explanation: You attempted to assign a logical device name to a 
pseudo device. Logical device names cannot be assigned to pseudo 
devices. 


-- Pseudo device redirect error 


Explanation: You attempted to redirect one pseudo device to 
another pseudo device. This is not allowed. 


-- R/O partition <pname> not in system, defaulting to task's 


Explanation: You specified a read-only partition that does not 
exist in the system. INSTALL will place the read-only portion of 
your multiuser task into the same partition as the read/write 
portion of the task. 


-- Receive data or by reference list not empty 


Explanation: A task with entries in its receive queues cannot be 
removed from the system image. 


-- Reference to memory beyond end of system image file 


Explanation: VMR attempted to fix a task, load a driver, or 
install a common beyond the space limits of the system image 
file. As a result, the command does not execute. 


-- Saved system truncated to n. blocks 


Explanation: (RSX-11S systems only.) VMR tried to save a system 
greater than n. blocks. This results in VMR truncating the saved 
image file to n.: 112(decimal) blocks for 28K-word systems’ saved 
on paper tape, 488(decimal) blocks for 122K-word systems saved on 
RXOl diskettes, and 496(decimal) blocks for 124K-word systems 
saved on all other bootable devices. 
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-- Space used 


Explanation: You attempted to create a partition in a_ storage 
area that is already occupied. 


-- Specified partition for common block 

Explanation: You attempted to install a task in a common block. 
-- Specified partition too small 

Explanation: This message can occur for the following reasons: 


1. You attempted to install a task into a partition that is 
smaller than the task. 


2. You attempted to install a driver into a partition that is 
smaller than the driver. 


-- Symbol <symname> is doubly defined by file <filename> 
Explanation: The symbol symname is defined twice in the 
specified file. Duplicate symbols are illegal. The driver is 
not loaded or unloaded. 


-- Symbol <symname> is undefined in file <filename> 


Explanation: LOAD found the symbol symname in the _ specified 
file, but the symbol is not defined. 


-- Syntax error 


Explanation: You have typed the command line incorrectly. 


. ~- System image is not RSX-11M-PLUS _ 


Explanation: You attempted to use RSX-11M-PLUS VMR on a 


non-RSX-11M-PLUS system image file. , 
-- System image is RSX-11M-PLUS 


Explanation: You attempted to use RSX-11M VMR on an RSX~-11M-PLUS 
system image file. 


-- Task active 


Explanation: The task you specified as an argument of the 
command is active. 


-- Task and partition bases mismatch 

Explanation: The base of the partition does not match that of 
the task being installed or of the driver being loaded. This 
message applies only to unmapped systems. 


-- Task or common region already fixed 


Explanation: You attempted to fix a task or common region in 
memory that is already fixed. 
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-- Task has attached common regions 
Explanation: This message can occur for the following reasons: 


l. You attempted to fix or unfix a task in memory that is linked 
to a shared region. VMR cannot fix or unfix such tasks. 


2. You attempted to remove a task that is linked to a= shared 
region from the system image. VMR cannot remove such tasks. 


-- Task image currently installed 
Explanation: You attempted to install a checkpointable task that 
has checkpoint space allocated in its task image. The task has 


already been installed. 


The system allows you to install checkpointable tasks more than 
once subject to the following rules: 


1. You must allocate checkpoint space for the task in a system 
checkpoint file. 


2. You must use a different name for the task each time you 
install it. 


-- Task image I/O error 
Explanation: The task cannot be installed or the driver cannot 
be loaded. VMR could not read the task image file or could not 
rewrite the task image header. The specified device may be 
write-locked. 

-- Task image virtual address overlaps common block <blockname> 
Explanation: The virtual addresses you reserved for the task 
image overlap those you reserved for the common block specified 
in the error message. Corruption of the task image file may have 
caused the overlap. 


-~ Task is checkpointable 


Explanation: You attempted to fix a checkpointable task in 
memory. Checkpointable tasks cannot be fixed. 


-- Task is not multi-user 

Explanation: You attempted to fix the read-only portion of a 
multiuser task in memory, but the task you named in the command 
line is not a multiuser task. 


-- Task name already in use 


Explanation: You attempted to install a task of the same name as 
that of one already installed in the system image. 


-- Task not installed with external header 

Explanation: This is a warning message to indicate that the 
specified task is installed with its header in pool (the dynamic 
storage region). 


-- Task not in system 


Explanation: You referenced a task that is not installed in the 
system. 
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-- Task not removed, CLI has messages enabled 

Explanation: You attempted to remove a CLI task that is able to 
receive messages from the system. The task may have messages 
that it has not received yet, so the remove request is aborted. 


-- Task or common not in memory 


Explanation: You attempted to remove a task or common from the 
system that is checkpointed and, therefore, not in memory. 


-- Task or common region is not fixed 


Explanation: You attempted to unfix a task that is not fixed in 
the system image. 


-- Task or common region not in system 

Explanation: You referenced a task or common region that has not 
been installed in the system or, on RSX-11M-PLUS, you attempted 
to run a prototype task. 


-- Task requires system controlled partition 


Explanation: You attempted to install a task that was built with 
external header (/XH) support and as checkpointable (TKB /CP, INS 
/CKP=YES). Such tasks must be installed in a system-controlled 
partition. 
-- TI redirect error 


Explanation: You attempted to redirect the pseudo device TI:. 
TI: cannot be redirected. 


-- TT redirect error 


Explanation: You attempted to redirect a terminal to the null 
device. This combination is not allowed. 


-- Too many common block requests 

Explanation: You attempted to install a task that contains too 
many common block requests. A task is limited to seven common 
block references. 


-- Too many LUNs 


Explanation: You attempted to install a task that contains more 
than 250(decimal) LUN assignment requests. 


-- Too many symbols of the form $xxTMO in file name 

Explanation: LOAD is attempting to extract symbols of the form 
$xxTMO from the driver's symbol definition file. There are more 
symbols of this form than LOAD can process. 


-- Top of pool set to <value>, requested amount not available 


Explanation: You requested more pool space than the system can 
provide. The system provides as much as possible in this case. 


-- Undefined common block <blockname> 
Explanation: You attempted to install a task that references a 


common block that is not defined in the system image. This 
message may indicate that the task was built for another system. 
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-- Unknown partition 


Explanation: You attempted an operation on a partition that does 
not exist in the system. 


-- User D-space not supported 

Explanation: An attempt was made to install a task with separate 
instruction and data space on a system that does not support user 
D-space. (User D-space is a system generation option.) 


-- Virtual terminal error 


Explanation: You attempted to enable, using the SET command, a 
terminal option for a virtual terminal. 


-- Write-check not supported for device 
Explanation: You attempted to enable write-checking for a device 


that does not support it. Write-checking is supported for all 
disks except RLOIs and RLO2s (DL:) and RXOls (DX:). 
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CHAPTER 11 


COMMAND LINE INTERPRETERS 


11.1 INITIAL CONCEPTS 


A command line interpreter, or CLI, is a task that services 
unsolicited commands meant for the operating system or an application. 
These commands are not prompted for by any task nor are they given to 
a task by a read operation on a terminal. 


The best-known CLI on RSX-11M and RSX-11M-PLUS systems is MCR, which 


controls the operating system. MCR, like any other CLI, receives 
command lines that originate as unsolicited input typed on a_ terminal 
Or as issued by a task using an Executive directive. Since all lines 


typed on a terminal are seen by the CLI (except those used to satisfy 
a task's read requests), the CLI task is, in effect, a complete user 
interface. This control over the user at the terminal is absolute. 
There is no way to bypass a CLI to send commands to the system or 
application. 


A CLI is also an efficient means of interfacing an application command 
processor to any number of terminals, since no read QIO or character 
AST processing is involved. The input from the terminal simply goes 
to the CLI by default for processing. 


This chapter introduces the concepts of CLIs_ on RSX~-11M and 
RSX-11M-PLUS systems. The chapter provides enough information to 
allow a programmer to write application-specific CLIs. A brief 
description of three DIGITAL CLIs supplied with the system illustrates 
these concepts. These three system CLIS do quite different things 
with the command lines they process, but the basic goal of each is the 
same: to provide a specific environment for the terminal user. This 
basic goal also applies to any application-specific CLIs, which, of 
course, may perform completely different command processing functions. 
A simple sample CLI - written in both FORTRAN and MACRO-11 - is 
included in this’ chapter. The example is also included on the 
distribution kit in either LB:[{1,2] with the HELP files or in the 
new-user directory [200,1] on RSX-11M_ systems, or [USER] on 
RSX-11M-PLUS, as TMCLI.MAC and TMCLI.FTN. See your system manager for 
more information. The example illustrates the CLI interface and 
should clarify the basic operations of a CLI. 


NOTE 
This chapter describes features available on RSX-11M 
and RSX-11M-PLUS. RSX-11S systems include Basic MCR, 


but do not support the CLI features discussed in this 
chapter. 
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11.1.1 MCR - The Traditional RSX-11M/M-PLUS CLI 


The most important CLI on RSX-11M/M-PLUS systems is MCR. MCR receives 
commands from the terminal and executes them to control the system. 
MCR is a set of privileged tasks. These tasks call Executive routines 
and interact with the system's data base. Therefore, MCR is tied very 
closely to the Executive. This bond is necessary because of MCR's 
function in system control and has nothing to do with MCR's role as a 
CLI. 


Most other CLIs interact with an application running on the system, 
rather than with the system itself. Therefore the CLI designer need 
not have any knowledge of RSX-11M/M-PLUS internals. In fact, the 
resulting CLI need not even be _ privileged. The only similarity 
between MCR and other CLIs is that any CLI controls the terminals 
associated with it just as MCR does. Every terminal on an 
RSX-11M/M-PLUS system is set to some CLI. Users can do nothing on 
their terminals that their CLI does not permit. The CLI controls the 
use of the terminal. 


NOTE 


While MCR is a CLI, it is a special CLI. MCR does not 
use the CLI interface directives because it must work 
on systems that do not support these directives. 
Therefore, MCR is not a pattern for other RSX-11M and 
RSX-11M-PLUS CLIs. 


11.1.2 DCL -— DIGITAL Command Language 


The DIGITAL Command Language (DCL) interpreter is a CLI that does not 
actually execute any commands. DCL provides an interface to operating 
system features by translating the commands it receives in DCL syntax 
to the equivalent MCR commands. DCL then passes the translated 
command line to the appropriate MCR task or utility for execution. 
The CLI interface hides this operation from the user at the terminal, 
who does not need to know about MCR or the utilities. DCL is oriented 
towards operations, such as COPY or LINK, rather than towards tasks 
like PIP and TKB. DCL presents a totally different external interface 
to RSX-11M/M-PLUS, one that is easier to learn and use than MCR. This 
makes it possible for less technical users to do work on 
RSX-11M/M-PLUS. 


11.1.3 RMT — DECnet Remote Terminal Facility 


The RMT task is a CLI that gathers commands from the terminals 
associated with it and sends them over a DECnet network to be executed 
on a remote RSX-11M/M-PLUS' system. The RMT interface provides a 
mechanism for command handling with a minimum of overhead or effect on 
user tasks. RMT is different from DCL: RMT does not interpret’ the 
command strings it handles, while all DCL does is interpret strings. 
All the interpretation and execution of commands passed through RMT is 
done by the CLI that receives the commands on the remote system. 


11.2 WRITING AN APPLICATION CLI 
A CLI is an RSX-11M/M-PLUS task, like any other. It need not be 


privileged unless the application requires it. Any alternate CLI is 
expected to interact with the operating system in a certain way, 
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however. This is necessary to synchronize with the operating system 
in command handling and prompting. This interaction is achieved 
through a set of Executive directives for CLIs. 


11.2.1 Executive Directives for CLIs 


The most important directive is GCCI$ (Get Command for Command 
Interpreter). GCCI$ must be used by every CLI, no matter what the CLI 
does. GCCI$ supplies a command to the CLI from a queue maintained by 
the system. It also controls the internal status bits necessary for 
correct synchronization of prompting and general command handling in a 
manner transparent to the CLI task. 


Other CLI directives include the following: 


1. RPOI$ (Request and Pass Offspring Information) and SDRP$ 
(Send, Request, and Pass), which can be used to pass the 
responsibility for handing a command off to another task so 
the CLI is free to handle another command. 


2. SCAAS$ (Specify Command Arrival AST), which specifies an AST 
in the CLI whenever a command arrives for processing by the 
CLI. 


3. GCII$ (Get Command Interpreter Information), which returns 
information about a terminal or CLI to the task. 


See the RSX-11M/M-PLUS and Micro/RSX Executive Reference Manual for a 


complete description of these directives. 


11.2.2 Basic Interaction with the Operating System 


Before a CLI can process commands, it must be made known to the 
system. This is done by installing the CLI task with the /CLI=YES 
switch and then initializing the CLI with the CLI /INIT command. This 
process creates an internal data structure that allows the system to 
recognize the existence of the CLI. See the RSX-11M/M-PLUS MCR 
Operations Manual for a description of the INSTALL command and the CLI 
commands. 


A CLI's operation starts when a command is entered into the system. 
The command may originate as a command line typed on a terminal or 


from an Executive directive issued by a_ task. The source of the 
command is generally irrelevant to the CLI. The command is processed 
first by the system command dispatcher (the MCR... task). This task 


puts the command into a FIFO queue of commands to be retrieved by the 
CLI. The CLI associated with the terminal from which the command 
originated is then requested to run (or unstopped if it is already 
active). The CLI gets the command from the system by issuing the 
GCCI$ directive. This directive removes a command from the CLI's 
queue and copies it into a buffer in the CLI's task space. GCCI$ can 
also supply information about the source terminal to the CLI. 


Once the CLI has the command, it is free to process it in any manner 
it chooses. Generally this involves executing the command, or passing 
the command to another task for execution. If the CLI is going to 
pass the command to another (non-CLI) task, it should use the RPOI$ or 
SDRP$ directive to do this, assuming the CLI has no further interest 
in the command. These directives propagate the information the system 
needs for controlling, prompting and getting exit status back to a 
parent task (if any). The CLI's obligations to the command are 
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complete once the command has been passed off; there is no reason for 
the CLI to get involved again. This is the recommended procedure for 
handling commands, as it avoids the wait for the preceding command to 
complete execution. DCL works in this way, translating a command into 
a different format and dispatching it to another task for execution. 


CLIs that process commands themselves should be very careful about 
handling any possible delays in execution. This is especially true if 
the CLI is to do I/O to a terminal; this means any terminal 1/0, 
including prompts for input. Otherwise, it would be very easy for one 
user to suspend command handling by not responding to a prompt or by 
pressing CTRL/S. 


Once a CLI has completed processing a command, it must reissue the 
GCCI$ directive to get any other command which may have been queued to 
it. If the CLI wants to stop or exit when no commands are queued to 
it, it should do this by issuing the GCCI$ directive with the 
appropriate no-command action specified. This prevents a command 
queved between the return from the GCCIS$ and the issuance of an EXIT 
or STOP directive from being lost, or not processed until the next 
command is queued. 


11.2.3 Task Names for CLIs 


CLIs can be installed with task names in the form ...xxx (commonly 
called a prototype task name) or with names in some other legal form, 
such as xxxxxx (commonly called a conventional task name). 


If the CLI has a prototype task name, the system creates a separate 
copy of the CLI each time a command is entered on a terminal set to 
that CLI. The task is named xxxtnn, following the same general rule 
as any other task installed in the system with a prototype task name. 
Each copy of the CLI runs with the same TI: and UIC as that of the 
terminal the command came from. These tasks should exit when there is 
no work left for them to do. 


If the CLI has a conventional task name, all commands from all 
terminals associated with the CLI are queued to a single copy of the 
task. This task runs with a TI: of CO: (console output pseudo 
device). CLIs with conventional task names must specify the TI: and 
UIC fields in any RPOI$ or SPWNS directives they issue, or the TI: 
and UIC will not default correctly. Because there is only one copy of 
these tasks in the system, CLIsS with conventional task names’ can 
simply stop (rather than exiting) when there are no commands queued 
for them. This may be necessary if the CLI must maintain information 
from one command to the next. 


DCL is installed with a prototype task name, ...DCL. RMT is installed 
as RMT..., with a conventional task name. The difference reflects the 
use and nature of each CLI. 


DCL must be installed with a task name of ...DCL because most DCL 
commands issue prompts for input. No command processing can be done 
by DCL while it is waiting for the user to respond to a = prompt. If 


there were only one copy of DCL on the system, command processing for 
all DCL terminals would stop while a prompt request to any one 


terminal was outstanding. This is clearly not an acceptable 
situation. Giving each terminal its own copy of DCL allows 
independent command processing for each terminal. To avoid filling 
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the system with copies of DCL, the individual copies of the task exit 
when no commands are left for them. They can do this because there is 
no need to maintain any context between commands. 


On the other hand, RMT is installed as RMT... because there can only 
be one copy of RMT in the system. This is because RMT provides a 
focal point with which the DECnet command handling software running on 
the remote system can communicate. Furthermore, it is not practical 
to have RMT exit when no commands are outstanding, because it is 
necessary to maintain context between commands. If each user got a 
separate copy of RMT, the system would be cluttered with copies of RMT 
that did not exit. 


11.2.4 MCR Control Commands 


The MCR CLI command is the means by which the system has knowledge of 
CLIs. The CLI command has switches which perform such functions as 
making a CLI known to the system, eliminating it from the system, 
turning on and off its recognition of commands, and so forth. See the 
RSX-11M/M-PLUS MCR Operations Manual for a description of the CLI 
command. ~~ 


11.2.5 System Messages to CLIs 


Depending on the nature of the CLI, it may be necessary for it to 
receive messages notifying the CLI of the occurrence of certain events 
that could effect it. If the /MESSAGE subkeyword to the CLI /INIT 
command is specified, it can receive messages from the system 
informing the CLI of such events. These messages are returned by the 
GCCI$ directive just like commands. - They can be differentiated from 
commands by the first word of the command buffer (G.CCDV) being 
cleared, instead of being set up with the name of the device from 
which the command originated. The code identifying which message is 
present is returned in the unit number byte (G.CCUN). The other 
fields have the same meaning for messages as they do for commands. 
The actual text field of the buffer may be empty if the message does 
not contain any ASCII text. See the RSX-11M/M-PLUS MCR Operations 
Manual for further information. 


NOTE 


The CLI command includes both a /MESSAGE subkeyword to 
the /INIT keyword and a /MESSAGE keyword. The 
/MESSAGE subkeyword specifies that the CLI being 
initialized can receive messages. The /MESSAGE 
keyword sends an ASCII message to a CLI that has’ been 
initialized with the /MESSAGE subkeyword. See the 
RSX-11M/M-PLUS MCR Operations Manual for further 
information. 


11.2.5.1 CLI Message Descriptions - Message codes 1 through 
127(decimal) are reserved for use by DIGITAL. Users wishing to create 
their own messages to CLIs should use codes in the range of 
128(decimal) through 255(decimal). The symbol shown for each message 
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code is defined in the Executive definition library: 
LB:[1,1]JEXELIB.OLB. Tasks may pick them up at build time by linking 
with that library. Messages are as follows: 
CLI Initialized into an Enabled Mode 
Message Code: 1 (CM.INE) 
Text: CLI name in RAD50, length = 4 bytes 
Explanation: This message is sent to a CLI when it is 
initialized by a CLI /INIT command without specifying the 
/DISABLE switch. 
CLI Initialized into a Disabled Mode 
Message Code: 2 (CM.IND) 
Text: CLI name in RAD50, length =. 4 bytes 


Explanation: This message is sent to a CLI when it is 
initialized by a CLI /INIT command with the /DISABLE switch. 


CLI Enabled 
Message Code: 3 (CM.CEN) 
Text: None. 


Explanation: This message is sent to the CLI when it is’ enabled 
by a CLI /ENABLE command. 


CLI Disabled 
Message Code: 4 (CM.CDS) 
Text: None. 


Explanation: This message is sent to the CLI when it is disabled 
by a CLI /DISABLE command. 

CLI Eliminated 
Message Code: 5 (CM.ELM) 
Text: None. 
Explanation: This message is sent to a CLI when it has’ been 
eliminated by an explicit CLI /ELIMINATE command. 

All CLIs Eliminated, and must Exit 
Message Code: 6 (CM.EXT) 
Text: None. 
Explanation: This message is sent to all cCLIS on the_ system 
which were initialized with the /MESSAGE subkeyword to the CLI 
/INIT command when a CLI /ELIM=* command is issued. A CLI that 


receives this message should exit as soon as possible, since 
system shutdown or other emergency procedure is taking place. 
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Terminal Linked to CLI 
Message Code: 7 (CM.LKT) 


Text: Name (ASCII) and unit number (octal) of terminal, length = 
4 bytes. (2 bytes each). 


Explanation: This message is sent to a CLI when a terminal 
becomes associated with it. This message could result from a SET 
command processed by MCR, or any other use of the _ SCLI$ 
directive. 


Terminal Removed from CLI 
Message Code: 8. (CM.RMT) 


Text: Name (ASCII) and unit number (octal) of terminal, length = 
4 bytes. (2 bytes each). 


Explanation: This message is sent to a terminal's former CLI 
when it is switched to another CLI. 


General Message 
Message Code: 9. (CM.MSG) 


Text: Name (ASCII) and unit number (octal) of terminal where the 
CLI /MESSAGE command originated, followed by the text from the 
command string. The length is equal to the length of the string 
(possibly zero) plus the length of the terminal name and unit 
number (2 bytes each). 


Explanation: This message is the result of a CLI /MESSAGE 
command. It contains whatever text the issuer of the command 
included in the string, plus the name and unit number of the 
terminal on which the command was typed. 


11.2.6 Prompts that Affect CLIs 


There are three kinds of prompts issued by the system that affect 
CLIs. These prompts are as follows: 


1. CTRL/C Prompts - This prompt is issued by the terminal 
driver when it receives a CTRL/C character. The string to be 
issued can be specified when the CLI is initialized. There 
is no way the CLI can be notified when this prompt is issued, 
however, since it is handled by the terminal driver. These 
prompts are of no other concern to CLIs. 
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2. Empty-Line Prompts - This prompt results from terminal input 
consisting solely of a carriage-return character, which is 
called a null command line. The standard system action is to 
have the MCR... task issue the default prompt, which can be 
specified when the CLI is initialized. The CLI can be 
initialized with the /NULL switch, which causes the system to 
send null command lines to the CLI like other commands, and 
not output anything. Any prompting or other action is 
therefore the CLI's responsibility. 


3. Task-Exit Prompts - These prompts are issued when ae task 
started by a command line exits. The standard system action 
is to have the MCR... task issue the same default prompt 


string as in the case of an empty line. If the CLI wishes to 
be informed of these occurrences, it can be initialized with 
the /PROMPT switch, which causes the system to send these 
task exit prompt requests to the CLI without terminal output. 
Any prompting or other action is then the CLI's 
responsibility. 


On RSX-1LIM-PLUS systems, a CLI initialized to receive either 
empty-line or task-exit prompts has to issue an _ SNXC$ 
directive when its processing of the ‘prompt is complete. 
SNXC$ tells the terminal driver that the current command is 
Comers | and — it can send the next one if the terminal is in 

irect can be issued if the 
ut any adverse effects. 
pa Frosegeing, for further 


farminal is nee ‘in s 
See Section il. 2, 6. 
details. 


11.2.7 System Handling of Continuation Lines 


Continuation lines are gibi 
before the command pas: 
command lines are ieee ad 
character | immediately pre 
removed and all the pieces of 
is aware of the command, 
continuation lines in any way 
interpret the presence of th yphen is 

the CLI can be initialized with the /SNGL 5 ch. thie eelia: the 
system to accept. single line commands only, She haps. every line to the 
CLI as it is entered. No continuation line checks are made. 


1M-PLUS terminal driver 
Incom lete Sets of 
££ aih me 


The DCL CLI on RSX-11M does its own handling of continuation lines. 
This is done within DCL itself, and is not available as a general 
system feature. This option is open to CLIs on RSX-11M systems, but 

is not necessary for CLIs on RSX-11M-PLUS as the system puts all the 
segments together before the command is sent to ‘the CLI. 


11.2.8 Interaction with Serial Command Processing (RSX-11M-PLUS only) 


Serial command processing is a ade in which commands from a terminal 
are executed in sequential | order, with a command not being started 
until the preceding command is finished. The default for command line 
processing on RSX-11M-PLUS systems is parallel processing, but a CLI 
may need to synchronize commands. Command synchronization is achieved 
by having the terminal driver store characters in the typeahead buffer 
if they are entered while a command is outstanding on that terminal. 
These characters are issued as the next command by a ‘special call to 
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11.3 SAMPLE CLI 


Following is a sample CLI, written in both MACRO-11 and FORTRAN. This 
sample CLI appears in the simplest form possible, so you can easily 
learn what is necessary to construct a CLI. The same MACRO-11 and 
FORTRAN programs used here are included on your kit as TMCLI.MAC or 
TMCLI.FTN. The primary function of TMCLI is to receive commands’ and 


pass them to MCR for execution. In addition, TMCLI features two 
single letter commands: T to type a file and M to switch back to MCR 
mode. The comments in each sample listing suggest several 


modifications that you can make when designing or setting up a CLI. 
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11.3.1 MACRO-11 CLI 


a ee ee ee Se | tC So Cr eS Se ee TS ee ee Te a eC Se eT te ee ts 


‘<> “> “ep 


eTITLE TMCLI ~- EXAMPLE CLI THAT IMFLEMENTS "T" ANT! "MN" COMMAND 
*+TQENT /1.00/ 


THIS TASK (TMCLI) ILLUSTRATES THE USE OF THE CLI CONTROL NIRECTIVES OF 
RSX~11M V4.0 ANT RSX-L1IM-FLUS V2.0, 


WHEN SET UF AS A TERMINAL ‘’S CLI,» IT FROVITES THE FOLLOWING COMMANT'S ¢ 


T > TYPE FILE 
M ~> SET TERMINAL TO MCR 


IF THE FIRST TWO LETTERS OF THE COMMANT ARE NOT "T" FOLLOWEN 

BY A SPACE, OR "M" FOLLOWED BY A CARRIAGE RETURN» 

THE COMMAND IS FASSED TO MCR FOR EXECUTION. THEREFORE» 

USERS AT TERMINALS SET TO THIS CLI WILL SEE THE ENTIRE MCR COMMAND SET 

AS BEING PRESENT» PLUS THE "T" ANT "M* COMMANTIS, IF THE /TFR SURKEYWORD 

IS INCLUDED ON THE CLI /INIT COMMAND: USERS WILL KNOW IMMEDIATELY IF 

THEIR TERMINAL IS SET TO THIS CLI BY THE DOURLE RIGHT ANGLE BRACKET FROMFT. 


IF TMCLI IS INITIALIZEN WITH THE /MESSAGE KEYWORSIs TMCLI WILL 
GREET USERS WHEN THETR TERMINAL IS SET TO THE CLI» AND SAY GOODBYE 
TO THEM WHEN THEY SWITCH AWAY. 


IN ORDER TO BRING THIS CL. UP ON THE SYSTEM» ISSUE THE FOLLOWING 
COMMAND SEQUENCES 


-MAC TMCL I» TMCLI/-SF=TMCLI 

“TKB TMCL Is TMCLI/-SP=TMCLI»CistIEXELIB/LE 

“INS TMCLI/CLI=YES/TASK=...TMC 

SPELT /SINTT=TMCLI/MESSAGE/DPR=*<15><122/2>/"°/TASK=..+TMC 


TO SET TERMINALS TO THIS CLI» ISSUE THE FOLLOWING COMMANNT 
WHERE TTNN$ IS REPLACED BY THE TERMINAL NUMBER OR TI? 


“SET /CLI=TTNN? TMCLI 


NOTE THAT THE FROMPT ISSUED IN RESPONSE TO A CONTROL/C TEFAULTS TO THE 
NAME OF THE CLT» WHICH IS "TMECLI>", 


TMCLI CAN BE ELIMINATED FROM THE SYSTEM BY THE FOLLOWING COMMANITS» ASSUMING 
NO TERMINALS ARE SET TO IT? 


SCLI /ELIM=TMCLI 
PREM ¢4 + TMC 


EXFERIMENT WITH THE OTHER SURKEYWORTIS OF THE CLI /INIT COMMANI!+s THF CLI 
7ENABLE ANT CLI /DISABLE COMMANDS: AND WITH THE /MESSAGE SWITCH ON THE /INIT 
COMMAND TO QRSERVE THE EFFECTS. ALSO TRY CHANGING THE /TASK= 

SWITCH ON THE INS AND CLI ZTINTT COMMAND TO "/TASK=TMCLI" AND NOTICE 

THAT ONLY ONE COFY OF THE TASK WILL EXIST FOR ALL TERMINALS» RATHER THAN 

ONE FER COMMANT. IF YOU GO THIS, YOU SHOULU ALSO CHANGE THE OFTTON 

ON THE GCCI¢$ DIRECTIVE FROM GC.CEX TO GC.CST SO THE TASK WILL STAY ACTIVE 
BUT STOPFEG WHEN NO COMMANI'IS ARE OUTSTANDING FOR IT. 


*MCOALL GCCISsRFOTS EXT TSS» QTOWS sr ALUNS STIRS 


DIRECTIVE DFBS 


11-10 


COMMAND LINE INTERPRETERS 


GCCTI$ GCCI$ CMDBUF sCBRLENy IBUF,y TRLEN20s6C.CEX 
RFOL: RFOIS$ MCORe ee 

QIOW: QIOWS TO.WVBeSrterseie sr 40> 

ALUN? ALUNS S 


; 
+ BUFFER AREAS 
5 
CMDBUFS .BLKB 80.+G.CCBF sLENGTH = HEATER PLUS COMMAND IN RYTES 
sNOTE THAT ON M-PLUS THE MAXIMUM COMMAND 
sLENGTH IS 255. BYTES» SO THE LENGTH SHOULD 
9RE <255.+G.CCRF> OR CHARACTERS MAY BE LOST. 
CBLEN=.-CMDBUF sCALCULATE LENGTH 
»EVEN 
IBUF $ + BLKB G.CCCAt2 sLONG ENQUGH TO CONTAIN ALL. INFORMATION 
IBLEN=.-IBUF sCALCULATE ILENGTH 
+EVEN 
TCM *ASCIT /FIFP TIs= sRASIC FIF COMMAND TO IMPLEMENT "T" COMMAND 
TCLEN=.-TCME sLENGTH OF COMMAND 
RUF «BLAKE 80.-TCLEN sRUFFER TO GENERATE COMMANTS IN 
«EVEN 
MCR *ASCIT /M/215> *STRING TO RECOGNIZE AS A SET TO MCR REQUEST 
MCMIIS “ASCII ZSET /MCR=TI2Z FSET TERMINAL TO MCR COMMAND 
MCLEN=.-MCMD sLENGTH OF COMMAND 
+EVEN 
; 
¢ TEXT TO BE DISPLAYED UPON RECEIFT OF NEW TERMINAL -LINKET OR 
¢ TERMINAL-REMOVED MESSAGES FROM SYSTEM. 
3 
LATS *ASCIT <152212>/WELCOME TO THE EXAMPLE CLI/“15><12> 
LRTLEN=.-LKT 
+EVEN 
RMT: *ASCIT £15><12>/600D RYE FROM THE EXAMPLE CLI/29S><122 
RMTLEN=.-RMT 
»EVEN 


MESSAGE FOR CHARACTERS LOST DUE TO BUFFER REING TOO SMAIL 


<a> “a> sap 


CHLOST? .ASCIIT “15><12>/SORRY» PART OF YOUR COMMAND WAS LOST/<15><12> 
CLLEN=.-CHLOST 


ILLEGAL COMMANT MESSAGE 


“<> “a> ser 


ILL 3 *ASCIT f15><122/71IL LEGAL COMMANT/<152<12> 
ILLLEN=.-ILL 
+ EVEN 
; 
y CLI COLE 
9 


+ENABL LSB 
START? DIRS #GCCI 9GET A COMMAND FROM SYSTEM 
BCS 100% 7IF £S»y DIRECTIVE ERROR 


y 
§ IF THE GCCI$ DIRECTIVE HAN THE GC.CST OPTION SFECIFIEIs WE MAY HAVE 
y JUST BEEN UNSTOFFED: SO WE HAVE TO GET THE COMMANE., 
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<a 


CMP #1S.CLR»$USW sWERE WE JUST UNSTOFPED? 

BEQ START yIF EQ YES 

MOV #CMDRUF » RO *POINT TO COMMANT BUFFER 

TST CRO) IS THIS A SYSTEM MESSAGE? 

BEQ MSG sIF EQ YES 

CMPB G.CCOCTCRO)*sG.CCCL(RO) $0ID ENTIRE COMMAND FIT IN BUFFER 
BLO 150$ sIF LO NO 

MOV #RPOTSRS sPOINT TO OPB OF RPOI$ OLRECTIVE 


AT THIS POINT» THE CLI HAS A COMMAND TO RE PROCESSED. THE CODE FROM 

THE "START$" LABEL TO HERE SHOULD BE FAIRLY COMMON AMONG ALL CLIS, 

FROM THIS POINT ON» THE CONE WILL BE SPECIFIC TO THE FARTICULAR LANGUAGE 
THIS CLI IS IMPLEMENTING. COMMANDS CAN RE ADDED OR DELETED AT WILL 

BY MODIFYING CONDE IN THIS SECTION. AS STATED ABOVEs THIS EXTREMELY 
SIMPLE CLI FROVIDES TWO COMMANDS: AND GIVES EVERYTHING ELSE TO MCR. 
THIS CREATES AN OPEN ENDED ENVIRONMENT. REJECTING UNRECOGNIZED COMMANIS 
INSTEAD OF FASSING THEM TO MCR WOULD LIMTT THE TERMINAL USER‘’S USE OF 
THE SYSTEM TO ONLY THOSE OPERATIONS ALLOWED BY THE CLI. THIS IS 

A SECURE WAY OF CONTROLLING SYSTEM USE,» IN CASES WHEN IT IS NECESSARY. 
IN THIS EXAMPLE» CHANGING THE "BNE S0O$* RELOWs TO A “BNE 60$" 

WOULD CREATE AN ENVIRONMENT WHERE THE ONIY OFERATTION A USER COULD 
FERFORM WOULT BE TO TYPE FILES ON THE TERMINAL» QR SWITCH RACK TO MCR. 
ALL OF THE REST OF THE SYSTEM IS INACCESSIBLE. IF NO MEANS OF SWITCHING 
KRACK TO MCR IS FPROVIDEN, IT IS IMFOSSIRLE FOR THE USER TO 0 

ANYTHING THE CLT DOES NOT EXPLICITLY LET HIM fO. 


“> “ap “GP ap E> “E> wed “GP “Ge “SP er ae we wee ee OP “ED ED 


CMF #°T »G.CCBRFCRO) $315 IT A "T" COMMANT? 
REQ 10% 9IF EQ YES 
CMF MCR»G-CCRFCRO) #¢IS IT AN "M* COMMANT? 


CHANGE THE NEXT INSTRUCTION TO "RNE 60%" TO ELIMINATE FASSING UNKNOWN 
COMMANDS TO MCR, 


<> “EP “er “ee 


BNE 10% 9IF NE NO 


THE USER HAS ENTERED AN "M" COMMANI!» SO SET THE TERMINAL TO MCR. 


<> ae “eo 


MOV #MCMDYR.FORFCRS) $FPUT ANDRESS OF CMI TO JSSUE IN TR 
MOV FMCLENSR.PORLCRS) sFUT LENGTH OF CMT IN UFR 
BR ISSCME s;ISSUE COMMAND 


THE USER HAS ENTERED A "T" COMMAND SO CONSTRUCT THE NECESSARY FIP 
COMMANT AND SEND TT TO MCR. 


<a> wer ~ep ‘oP 


1083 MOV ROyR1 *COFY ADRESS OF BUFFER WITH COMMAND 
Ann #G.CCBF+isR1 yFOINT TO SPACE AFTER THE T 
MOV #KUF 9 RO sFOINT TO BUFFER THAT WILL CONTAIN CMD 
MOV #TCLENSR4 9GET LENGTH OF INITIAL PART OF COMMAND 
2083 MOVE (RL) +9R3 +GET NEXT CHARACTER 
CMFR #159R3 #1S IT THE END OF THE COMMANT 
REQ 30% ,IF EQ YES 
CMFR #409R3 71S TT A SFACE 
REQ 20% s;IF EQ YES» SKIF IT 
MOVE R3y(R2)+ yFUT CHARACTER IN OUTPUT BUFFER 
INC R4 sCOUNT CHARACTER 
BR 2O$ iGET NEXT CHARACTER 
J0%5 MOV #TCMDeR.PORF CRS) SPUT ANDRESS OF CMI TO ISSUE IN IPB 
MOV R4eR.FPORL CRS) yINSERT LENGTH OF COMMAND 
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THIS COMMAND WILL BE PASSED TO THE MAIN COMMAND DISPATCHER (MCR...)» 
WHICH WILL START A COPY OF FIF AND GIVE IT THE COMMAND. THE RFOT 
DIRECTIVE COULD BE USED TO GIVE THE COMMAND DIRECTLY TO ..-FPIF AND 
GIVE THE RESULTING TASK A DIFFERENT NAME. IN THIS EXAMPLE» 

WE COULD CALL THE RESULTING PIF TASK "TYPTNN" WHERE THE LAST 

THREE CHARACTERS (TNN) ARE REPLACED BY A DEVICE NAME CHARACTER ANDI 
UNIT NUMBER. FOR EXAMPLE? IF THE ‘T"* COMMANLI WAS TYPED ON TT10; 

THE RESULTING TASK NAME COULT BE MADE TO BE “"TYPT1O". THIS HAS THE 
ADVANTAGE OF ALLOWING THE TASK TO BE ABORTED BY AN “ABO TYP" COMMAND 
INSTEAD OF “ABO PIF", THUS THE USER WOULD NOT HAVE TO KNOW THAT THE 


IS EXACTLY WHAT THE DCL CLI NOES. IF I5 NOT DONE HERE 
TO SIMPLIFY THE EXAMPLE. FICKING UF THE TERMINAL NAME AND UNITY 
(BE CAREFUL ON RSX-11M-PLUS SYSTEMS WITH MORE THAN 64. TERMINALS), 


OVERHEAD. 


“ar SP GP > “EP “E> ~er “E> “arp “Oh EP E> “EP NEP “EP EP ee er er 


BR ISSCMD yEXECUTE COMMAND 


COMMAND IS NOT "T" OR "M"» SO GIVE IT TO MCR AS IS. 


Ci ~e> ~e> <=> 


MOVE G.CCCTCRO*sR.FOBL(RS) sPUT LENGTH IN RFO] DFR 


ISSUE RPOI$ DIRECTIVE TO EXECUTE COMMAND 


a 
; 
a 
; 
‘ 
; 
I 


SSCMD: MOV (RO) eR.FPODVCRS) sFPUT NAME OF ISSUING DEVICE IN RFOI 
MOVB G.CCUNCRO)»R.POUNCRS) 5COFY UNIT NUMBER 
MOVB IBUF+tG.CCFUSR.POUMCRS) sFROFAGATE UIC OF TERMINAL 
MOVE IBUFtG.CCFUtI sR. POUGCRS) 
MOV IBUF+G.CCOA»R.FPOOACRS) sCORFY ITD PARENT IN CASE WE WER 
LIRS #RFOL +FPASS COMMAND TO EXECUTOR TASK 
BCC START *IF CCy SUCCESS 
BR 110% yERROR 


CONTROL IS TRANSFERRED HERE IF UNKNOWN COMMANDS ARE TO BE REJECTED 
INSTEAD OF BEING PASSED TO MCR. 


On ~er ~em sem er 


0$3 MOV #ILLsRi sFOINT TO MESSAGE TO BE FRINTED 
MOV FILLLEN®R2 *GET LENGTH OF MESSAGE 
CALL ISSMSG sISSUE MESSAGE 
BR START *TRY FOR NEXT COMMAND 


ERROR HANDLING CORE 


<> > <a> 


100$3 CLR RO *FATAL ERROR ON GCCI$ 
BR 150% 
110$3 MOV #1»RO0 *;FATAL ERROR ON RFOI$ 
12083 TOT 7FATAL 
150$3 MOV #CHLOSTrR1 #POINT TO MESSAGE TO BE FRINTED 
MOV #CLLEN?R2 3GET LENGTH OF MESSAGE 
CALL ISSMSG yISSUE MESSAGE 
BR START 
»-DSABL LSB 


ry 
3 
ry 
? 


A SYSTEM MESSAGE WAS RECEIVED INSTEAD OF A COMMAND. 
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"T" COMMAND HE ISSUED IS ACTUALLY BEING SERVICED BY THE FIP TASK. THI 


NUMBER» CONVERTING IT TO RADSO» ANTI SUPPLYING IT IN THE RPOI DYTRECTIVE 
ALONG WITH A DIRECT REQUEST OF PIP BB LEFT AS AN EXERCISE TO THE USER. 


0$3 MOV #CMDBUFt+G.CCBFeR.FOBFC(RS) ¢FUT ADDRESS OF STRING IN [FEB 


NOTE THAT REQUESTING FIF DIRECTLY AVOIDS A SUBSTANTIAL AMOUNT OF SYSTEM 


os 


2 


FPAWNET 


COMMAND LINE INTERPRETERS 


MSG CMFB #CM.LKT»G.CCUN(RO) 51S IT A NEW TERMINAL LINKED TO US? 
BEQ 10% sIF EQ YES 
CMFB #CM.RMTYG.CCUNCRO) $1S IT A TERMINAL REING REMOVED 
BEQ 20% ¢IF EQ YES 
CMFB #CM.EXT»G.CCUNCRO) ¢IS IT AN ELIMINATE ALL FACKET 
REQ 50$ sIF EQ YES 
CMP ER #CM.ELM»sG.CCUNCRO) $15 IT A CLI ELIMINATION MESSAGE 
BEQ 50$ sIF EQ YES 
BR START IGNORE ALL OTHER MESSAGES 


ISSUE WELCOME MESSAGE 


> “er er er 


O$s MOV #LKT»R1 sFOINT TO MESSAGE TEXT 
MOV FL KTLENsR2 sGET LENGTH 
ADD #G.CCRF»RO sFOINT TO TERMINAL THAT WAS SET 
ER 30% ; 


ISSUE GOODBYE MESSAGE 


PJ wee “> <> 


O$s MOV #RMT RL sPFOINT TO MESSAGE TEXT 
MOV #RMTLENSR2 9GET LENGTH 
ALT #6.CCBFrRO sPOINT TO TERMINAL NAME 
30$% CALL ISSMSG PTSSUE MESSAGE 
IMP START 9GET NEXT COMMAND 


WHEN AN ELIMINATE ALL MESSAGE IS RECEIVED: EXIT IMMEDIATELY. 


Ch wep sae wee 


OS} EXIT$S 


ROUTINE TO FRINT TO TERMINAL 


INFUTS? 


RO=ADDRESS OF NAME OF TERMINAL TO FRINT TO 
Ri=ADDRESS OF MESSAGE TO FRINT 
R2=LENGTH OF MESSAGE 


OUTFUTS?: 
NONE 


THIS ROUTINE PRINTS THE SPECIFIED MESSAGE ON THE SFECIFIEN TERMINAL. 
ALL ERRORS THAT MIGHT RESUILT ARE TGNORED. IN GENERAL, CLIS SHOULD 

LQ ASYNCHRONOUS I/0 WITH COMFLETION ASTS» ANI! FROVINE A TIME-OUT 
FACILITY TO KILL THE 1/0 IF IT HASN’T COMPLETED IN A CERTAIN 

AMOUNT OF TIME. THIS FREVENTS TERMINAL T/0 FROM HOLTNING UF 

COMMAND FROCESSING., THIS IS NOT DONE HERE FOR SIMPLICITY. 


SP Td 


ISSMSG: MOV CROPALUNtA-LUNA §SET UP DEVICE NAME 
MOVE 2(RO)sALUN+A.LUNU SAND UNIT NUMBER 
CLRR ALUN+A.LUNUT] *CLEAR HIGH BYTE 
LIRS ¥ALUN sASSIGN LUN S TO THE SFECIFTED TEVICE 
RCS 10% ¢IF CS» SKIF I/0 
MOV RisQTOW+Q.INFL sSET ATDURESS OF MESSAGE 
MOV R29QTOW+Q. IOPL+2 FINSERT LENGTH OF MESSAGE 
LIRS #QTOW sN0 1/0 AND WATT FOR IT 
10$% RETURN 
«ENT START 
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11.3.2 FORTRAN CLI 


THIS TASK (TMCLI) ILLUSTRATES THE USE OF THE CLI CONTROL DIRECTIVES OF 
RSX-11M V4.0 ANU RSX-1LIM-PLUS V2.0. 


WHEN SET UP AS A TERMINAL’S CLI» IT FROVIDES THE FOLLOWING COMMANTS? 


: ~? TYPE FILE 
M ~e SET TERMINAL TO MCR 


IF THE FIRST TWO LETTERS OF THE COMMAND ARE NOT "T* FOLLOWET 

BY A SFACEs OR "M" FOLLOWED BY A CARRIAGE RETURN, 

THE COMMAND IS PASSED TO MCR FOR EXECUTION. THEREFORE » 

USERS AT TERMINALS SET TO THIS CLI WILL SEE THE ENTIRE MCR COMMAND SET 

AS BEING FRESENT:s FLUS THE "T" ANID *M" COMMANTIS. IF THE /DPR SURKEYWORD 

TS INCLUDED ON THE CLI /INIT COMMAND: USERS WILL KNOW IMMEDTATELY IF 

THEIR TERMINAL IS SET TO THIS CLI BY THE DOURLE RIGHT ANGLE BRACKET FROMFT. 


IF TMCLI IS INITIALIZED WITH THE /MESSAGE KEYWORMT» TMCLI WILL 
GREET USERS WHEN THEIR TERMINAL IS SET TO THE CLiIs AND SAY GOONBYE 
TO THEM WHEN THEY SWITCH AWAY. 


IN ORDER TO BRING THIS CLI UF ON THE SYSTEM, ISSUE THE FOLLOWING 
COMMANT SEQUENCE? 


FOR TMCLIysTMCLI/-SF=TMCLI 

*TKRB TMCLI/FPsTMCLI/~SP=TMCLIsCistIFOROTS/LB 

2INS TMCLI/CLI=YES/TASK=...TMC 

CLI /INTT=TMCLUI/MESSAGE/DPR="<15><122/2>/"/TASK=.66 TMC 


IF USING FORTRAN IV-FLUS INSTEAD OF FORTRAN IVy THE FIRST TWO 
COMMANDS ABOVE WOULD BE? 


>F4P TMCLI»TMCLI/-SP=TMCLI.FTN 
2TRB TMCLI/FP es TMCLI/-SP=TMCLOyCisi JF4POTs/ le 


TO SET TERMINALS TO THIS CL.I» ISSUE THE FOLLOWING COMMAND 
WHERE TTNN? IS REPLACED BY THE TERMINAL NUMBER OR TI? 


SET /CLI=TTNNS TMCLI 


NOTE THAT THE FROMFT ISSUED IN RESPONSE TO A CONTROL/C DEFAULTS TQ THE 
NAME OF THE CLIs WHICH TS "TMCLI>". 


TMCLI CAN BE ELIMINATED FROM THE SYSTEM BY THE FOLLOWING COMMANI'S» ASSUMING 
NO TERMINALS ARE SET TO IT: 


CLI /ELIM=TMCLI 
SREM «++ TMC 


EXPERIMENT WITH THE OTHER SUBRKEYWORDS OF THE CLI /INIT COMMAND, THE CLI 
7ZENABLE AND CLI /DISABLE COMMANDS,» AND WITH THE /MESSAGE SWITCH ON THE /INIT 
COMMAND TO OBSERVE THE EFFECTS. ALSO TRY CHANGING THE /TASK= 

SWITCH ON THE INS AND CLI /INIT COMMAND TO "/TASK=TMCLI* AND NOTICE 

THAT ONLY ONE COFY OF THE TASK WILL EXIST FOR ALL TERMINALS» RATHER THAN 

ONE PER COMMAND. IF YOU DO THIS» YOU SHOULD ALSO CHANGE THE OPTION 

ON THE GTCMCI DIRECTIVE FROM GC.CEX TO GC.CST SO THE TASK WILL STAY ACTIVE 
BUT STOPPED WHEN NO COMMANDS ARE OUTSTANDING FOR IT. 


AOOKOAGAAAAOAAAIAAKADAAAAKRDAIAGAANAAKGRDANAAINAAAARCAAAHIAASKOANI AANA aAnrantinraann 
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BUFFER AREAS 


COMMAND BUFFER - THIS BUFFER IS USE IN THE GTCMCT TNTRECTIVE. IT CON- 
TAINS INFORMATION ON THE COMMAND RECEIVED (8 RYTES) 
AND THE COMMAND TEXT. 
BYTE CMDBUF (264) 


INTEGERK2 CBLEN ! NOTE THAT ON M+ THE MAXIMUM COMMANT 
DATA CBLEN/2463/ ! LENGTH ITS 255. 
INTEGERK2 GCCDV,s GCCCL ! ASCII TEV NAM» # CHARS IN CMI LINE 


BYTE GCCOCT:s GCCUNs GCCBFC(255) ! # OF CHARS» TERMINAL UNIT #»* CMD 
EQUIVALENCE (GCCIUV»sCMDBUF)» (GCCCL»CMIBUF(S)), (GCCCT»CMDUBUF(4))» 
1 (GCCBF sCMNBUFC9))» (GRCOUN*sCMOBUF (3) ) 


INFORMATION BUFFER ~ ALSO RETURNED IN THE GTCMCI DIRECTIVE. 
BYTE IBUF (14) 
INTEGERK2 GCCFU 
DATA TBLEN/14/,GCCPU/9/ |! LENGTH OF IBUF» LOGIN UIC OFFSET 
INTEGER*4 GCCOA ! ADUR OF OFFSFRING CONTROL BLOCK FROM PARENT 
EQUIVALENCE (GCCOA»TIBUF(7)) 

BUFFER IN WHICH TO GENERATE COMMANDS 
BYTE BUF C72) ' BUFFER IN WHICH TO GENERATE COMMANTS 
REALXS TCME(C2) ' FOR CONVENTENCE IN ASSTGNMENT STATEMENTS 
EQUIVALENCE (BUF sTCMI) 

MCR TASK NAME IN RATSO 


INTEGER*4 IMCR ! MCR TASK NAME IN RATISO 
DATA IMCR/6RMCR...7/ 


DIRECTIVE SYMBOLIC VALUE DEFINITIONS 


INTEGER*2 GCCCS, GCCEX» GCCST» GCCND 


DATA GCCCS:, GECEXs GECST»s GCCNT /Or ty 2e 1287 ! INCPF VALUES IN GTCMCI 
DATA ISCLR /0/ ! IS.CLR RETURN CONE 
INTEGERK2 CMELMs CMEXTs CMILKT»s CMRMT ! TERMINAL COTES FOR SYSTEM MSGS 


DATA CMELM:s CMEXTs CMLKT» CMRMT /Se 62 7x 8/ 
CLI CODE 


TO FORCE THE CLI TO EXIT INSTEAD OF RETURNING: THE GC.CEX OFTION IS SFECI- 
FIED IN THE GTCMCI DIRECTIVE BELOW. IF THE CLI IS TNSTALLED SO THAT ONLY 
ONE COFY OF THE TASK WILL EXIST FOR ALL TERMINALS» CHANGE THE VARIABLE 
GCCEX BELOW TO GCCST. THIS SPECIFIES THE GC.CST OFTION SO THAT THE TASK 
WILL STAY ACTIVE BUT STOPPED WHEN NO COMMANDS ARE OUTSTANDING FOR IT. 


1 CALL GTCMCI(CMDBUFSCBLENyIBUFSITBLEN»O»GCCEX»sINS) ! GET CMD FOR CLI 
IF (InS .LT. 0) GO TO 100 


IF THE GTCMCI DIRECTIVE HAD THE GC.CST OPTION SPECIFIED: WE MAY HAVE 
JUST BEEN UNSTOPFED, SO WE HAVE TO GET THE COMMAND. 


IF (IDS .€Q@. ISCLR) GO TO 1 ! WERE WE JUST UNSTOFFPED? 

IF (GCCUV .EQ. 0) GO TO 200 ! IS THIS A SYSTEM MESSAGE? 

IGCCUN = GCCUN ! CONVERT BYTE TO INTEGER (UNIT #) 
CALL ASNLUN(S*sGCCOV,IGCCUN, T0S) |! ASSIGN TERMINAL TO LUN S 
IGCCCT=GCCCT 1 CONVERT BYTE TO INTEGER 

IF (IGCCCT .GE. 0) GO TO 5 

TGCCCT = 256 + IGCCCT ' CONVERT NEGATIVE TO UNSIGNED 


IF (I6CCCT LT. GCCEL) GOTO 150 ! UT ENTIRE COMMAND FIT IN BUFFER? 


cn 
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AT THIS POINT» THE CLI HAS A COMMANT TO BE PROCESSED. THE CONE FROM 

THE LABEL 1 TO HERE SHOULUT BE FAIRLY COMMON AMONG ALL CLIS. 

FROM THIS FOINT ON» THE CONE WILL BE SPECIFIC TO THE FARTICULAR LANGUAGE 
THIS CLI TS IMPLEMENTING. COMMANTIS CAN RE ANDED OR NELETED AT WILL 

BY MODIFYING COMBE IN THIS SECTION. AS STATED AROVEs THIS EXTREMELY 
SIMPILE CLI PROVIDES TWO COMMANDS, AND GIVES EVERYTHING ELSE TO MCR. 
THIS CREATES AN OPEN-ENDED ENVIRONMENT. REJECTING UNRECOGNIZED COMMANDS 
INSTEAN OF FASSING THEM TO MCR WOULU LIMIT THE TERMINAL USER’S USE OF 
THE SYSTEM TO ONLY THOSE OPERATIONS ALLOWED BY THE CLI. THIS IS 

A SECURE WAY OF CONTROLLING SYSTEM USE» IN CASES WHEN IT TS NECESSARY. 
IN THIS EXAMPLE» CHANGING THE "GO TO SO* BELOW» TO A "GO TO 60" 

WOULT) CREATE AN ENVIRONMENT WHERE THE ONLY OPERATION A USER COULD 
FERFORM WOULD BE TO TYPE FILES ON THE TERMINAL» QR SWITCH BACK TO MCR. 
ALL OF THE REST OF THE SYSTEM IS INACCESSTELE. IF NO MEANS OF SWITCHING 
BACK TO MCR IS PROVIDED, IT IS IMPOSSIBLE FOR THE USER TO fo 

ANYTHING THE CII DOES NOT EXPLICITLY LET HIM DO. 


IS IT A "T* COMMAND? 
IF ((GCCBF(1) .EQ. °T’) ANT. (GCCBF(C2) .EQ. % ’)) GO TO 10 


CHANGE THE NEXT IF STATEMENT TO "GO TO 60° TO ELIMINATE FASSING UNKNOWN 
COMMANIIS TO MCR. 


IS IT ALSO NOT AN "MM" COMMANT? 
IF ((GCCBRFC1) «NE. °M’) .OR, (GCCRFC(2) «NE. 13)) GO TQ SO ! MeCR> 


THE USER HAS ENTERED AN "M" COMMAND» SO SET THE TERMINAL TO MCR. 


TOMEI) = “SET /MCR’ 

TCOMDC2) = %=TI3 ‘ 1 SET /MCR=TI?: 

IGRF = IBUF(GCCPUtT1) 1 (CONVERT BYTE TO INTEGER) GROUF 
INEM = IBUFCGCCPU) ' MEMBER PART OF UIC 


ISSUE RFOI$ DIRECTIVE TO EXECUTE COMMAND 


CALL RPOICIMCRe IGRE» IMEMs » TCM 912% »GCCNV,sIGCCUN» »GCCOAPTIDS) 
IF (IDS .LE. 0) GO TO 110 ! ERROR? 
GO TO 1 ! BACK TO START 


THE USER HAS ENTERED A "T" COMMAND SO CONSTRUCT THE NECESSARY PIP 
COMMAND AND SEND IT TO MCR 


10 TCMD(1) = “PIP TIit=’ 1 PUT BEGINNING OF PIP CMD IN BUFFER 
I2 = 8 ! POINTER INTO TARGET BUFFER 
10 20% Ii = 10» CBLEN ' BEGIN AT SPACE AFTER THE T IN CMItRUF 


IF (CMDBUF(I1) .EQ. 13) GO TO 30 ! END OF COMMAND? (<CRY) 
IF (CMDBUFCI1) .EQ@. ’ ’) GO TO 20 ! SKIP ANY SPACES 


12 = 12+ 1 ! COUNT CHARACTER 
BUF(I2) = CMDBUFCI1) ! COPY INTO OUTPUT BUFFER 
20 CONTINUE 
30 IGRF = IBUFC(GCCPUt1 > 1 (CONVERT BYTE TO INTEGER) GROUF 
IMEM = IBUFCGCCPU) ! MEMBER PART OF UIC 


ISSUE RFOI$ DIRECTIVE TO EXECUTE COMMAND 
CALL RPOICIMCRe IGRP» IMEMy» TCMD eT 2s »GCCUV,sIGCCUN» »GCCOA*YIDS) 


IF (IBS .LE. 0) GO TO 110 ! ERROR? 
GO TO l ! BACK TO START 
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IN THE ABOVE SECTION OF CODE, THE RPOI DIRECTIVE WAS USED TO FASS 

THE FIP COMMAND TO THE MAIN COMMAND DISPATCHER (MCR...) » 

WHICH WILL START A COFY OF PIP AND GIVE IT THE COMMAND. THE RFOLI 
DIRECTIVE COULD BE USED TO GIVE THE COMMAND DIRECTLY TO ...PIF AND 
GIVE THE RESULTING TASK A DIFFERENT NAME. IN THIS EXAMPLE» 

WE COULD CALL THE RESULTING FIP TASK "TYPTNN" WHERE THE LAST 

THREE CHARACTERS (TNN) ARE REPLACED BY A DEVICE NAME CHARACTER AND 
UNIT NUMBER. FOR EXAMPLE» IF THE “T" COMMAND WAS TYPED ON TT10$ 

THE RESULTING TASK NAME COULD BE MADE TO BE "TYFT10"°. THIS HAS THE 
ADVANTAGE OF ALLOWING THE TASK TO BE ABORTED BY AN “ABO TYF" COMMAND, 
INSTEAD OF "ABO PIF** THUS THE USER WOULD NOT HAVE TO KNOW THAT THE 
*T* COMMAND HE ISSUED IS ACTUALLY BEING SERVICED BY THE FIP TASK. THIS 
IS EXACTLY WHAT THE DCL CLI DOES. IT IS NOT DONE HERE IN ORDER 

TO SIMPLIFY THE EXAMPLE. FICKING UP THE TERMINAL NAME AND UNIT 

NUMBER» CONVERTING IT TO RADSOrs AND SUPPLYING IT IN THE RFOI DIRECTIVE 
ALONG WITH A DIRECT REQUEST OF PIF IS LEFT AS AN EXERCISE TO THE USER. 
(BE CAREFUL ON RSX-1L1M-FLUS SYSTEMS WITH MORE THAN 64. TERMINALS). 
NOTE THAT REQUESTING FIF DIRECTLY AVOIDS A SUBSTANTIAL AMOUNT OF SYSTEM 
OVERHEAD. 


COMMANT IS NOT "T* OR "M"s SO GIVE IT TO MCR AS IS. 


30 IGRP = IBUF(GCCPUt1) ' (CONVERT BYTE TO INTEGER) GROUF 
IMEM = IBUF(GCCFU) ! MEMBER FART OF UIC 
IGCCCT = GCCCT ' # OF CHARS IN COMMAND 

ISSUE RPOI¢$ DIRECTIVE TO EXECUTE COMMAND 
CALL RPOICIMCRe IGRP» IMEM, +GCCRF, IGCCCTs »GCCOVs IGCCUN? »GCCOArIDS) 
IF (IDS .LE. 9) GO TO 110 ! ERROR? 
GO TO i ' BACK TO START 

CONTROL IS TRANSFERRED HERE IF UNKNOWN COMMANDS ARE TO BE REJECTED 

INSTEAD OF BEING FASSED TO MCR. 

60 WRITE (5962) 

62 FORMAT(‘OILLEGAL COMMAND’ > 
GO TO 1 ! BACK TO START 

ERROR HANDLING CODE 

100 WRITE (52102) IDS ! ERROR IN GTCMCI 

102 FORMAT(’OFATAL ERROR IN GTCMCI DIRECTIVE. ESW=’,T6) 
GO TO 250 ! EXIT 

110 WRITE (S9112) IDS ! ERROR IN RFOLI 

112 FORMAT(’OFATAL ERROR IN RPOI BIRECTIVE., DSW=’sI4) 
GO TO 250 ! EXIT 

90 WRITE (59152) ! ENTIRE COMMAND DID NOT FIT IN BUFFER 

152 FORMAT(‘OSORRY» PART OF YOUR COMMAND WAS LOST’) 
GO TO i ' BACK TO START 


A SYSTEM MESSAGE WAS RECEIVED INSTEAD OF A COMMAND 


200 CONTINUE 


IF (GCCUN .EQ. CMLKT) GO TO 210 ! IS IT A NEW TERMINAL LINKED TO US? 
IF (GCCUN .EQ. CMRMT) GO TO 220 ! IS IT A TERMINAL BEING REMOVED? 
IF (GCCUN .EQ. CMEXT) GO TO 250 ! IS IT AN ELIMINATE ALL PACKET? 

IF (GCCUN .EQ. CMELM) GO TO 250 ! IS IT A CLI ELIMINATION MESSAGE? 
GO TO 1 ! IGNORE ALL OTHER MESSAGES 
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C 

C ISSUE WELCOME MESSAGE 

C 

210 IGCCUN = CMIBUF (11) ! CONVERT BYTE TERMINAL. UNTT # TO INTEGER 


CALL ASNLUN(CS*sGCCBFr,rIGCCUNs IOS) ! ASSIGN LUN 5 TO SFECIFIED DEVICE 
WRITE (52212) 

212 FORMAT(‘OWELCOME TO THE EXAMPLE CLI’) 
GO TO 1 ! BACK TO START 


c 
C ISSUE GOODRYE MESSAGE 


220 IGCCUN = CMDBUF (11) 1 CONVERT BYTE TERMINAL UNIT # TO INTEGER 
CALL ASNLUNCS»GCCBF,IGCCUN,sIOS) ! ASSIGN LUN 5S TO SPECIFIED DEVICE 
WRITE (57222) 

222 FORMAT(’OGOOR BYE FROM THE EXAMPLE CLI’) 


GO TO i ! BACK TN START 
C 
C WHEN AN ELIMINATE ALL MESSAGE IS RECEIVED» EXIT IMMENTATELY 
C 
250 CONTINUE 
CALL EXIT 
ENI 
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CHAPTER 12 


THE DCL TASK 


The DIGITAL Command Language (DCL) is a general purpose command 
language syntax implemented on several DIGITAL operating systems. 


12.1 INTRODUCTION 


DCL on RSX-11M/M-PLUS systems is a task that receives DCL commands by 
means of the generalized CLI command dispatcher, translates the DCL 
commands to equivalent MCR commands, and sends the MCR commands to the 
MCR command line interpreter for interpretation and execution. The 
DCL task, in conjunction with the CLI dispatcher, provides DCL support 
on RSX-11M/M-PLUS operating systems. 


This chapter explains the ways in which DCL can be installed on your 
system and documents the means by which the DCL task parses and 
translates commands. In addition, this chapter documents the Macro 
MetaLanguage, a set of MACRO-11 macros used to define DCL. An 
experienced programmer can add commands to DCL or remove them, or 
alter DCL by changing parts of it, such as altering defaults or 
eliminating qualifiers. 


For information on DCL syntax and functions, see the RSX-11M Command 
Language Manual or the RSX-11M-PLUS Command Language Manual. For 
information on MCR syntax and functions, see the RSX-11M/M-PLUS MCR 
Operations Manual. For information on the CLI command dispatcher, and 
on alternate CLIs, see Chapter 11, Command Line Interpreters, in this 
manual. For information on the Executive directives used to implement 
alternate CLIs, see the RSX-11M/M-PLUS and Micro/RSX Executive 
Reference Manual. -— 


The examples of source code in this chapter illustrate features of DCL 
and the DCL task, but they are often changed from the actual source 
code to make the example clearer. See the DCL source code in [23,10] 
for exact information. The command tables for the ASSIGN command are 
included in this chapter (Section 12.11.6) as a general example of DCL 
coding. 


12.2 INSTALLING AND BUILDING DCL 


The DCL task is best installed as an alternate CLI, but it can also be 
run as a task or installed as an external MCR task. External MCR 
tasks have task names in the form ...abc. Furthermore, you can 
rebuild DCL either to eliminate direct access to MCR from DCL, or to 
allow all commands not in DCL syntax to fall through DCL for handling 
by MCR. Your choice on these options depends on the requirements of 
your system users and your installation. 
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12.2.1 Conventional Installation of DCL as a CLI 


Installing DCL as an alternate CLI is the cleanest use of DCL. This 
allows you to classify users by CLI in the system account file. Users 
can log in using either HELLO or LOGIN. The HELLO task checks’ the 
account file for the CLI and sets the user's terminal to the 
designated CLI. 


On RSX-11M systems, DCL and alternate CLI support require a mapped 


system with multiuser protection. If you choose DCL at system 
generation, you are also choosing alternate CLI support, as DCL is an 
alternate CLI. In addition, choosing DCL support also gives you 


support for the following directives: 
@ Stop-bit 
e Install-request-remove 
e Parent-offspring tasking with chaining 
@ AST 
@ Specify request exit AST 
@e Get task parameters 
@ Get command for command interpreter 
@ Request and pass offspring information 
@e Specify command arrival AST 
e Get command interpreter information 
The last four directives listed are those specifically added for 


alternate CLI support. See Chapter 11, "Command Line Interpreters," 
and the RSX-11M/M-PLUS and Micro/RSX Executive Reference Manual. 


eet rr 


, you are asked if you want 
The other (non-CLI) directives 
all : SSX-1IMSPLOS | ae Seen bhe 


a poet, evaten generation on. -RSX-1 


S Pp 
full-function Meucceive, | 


Installing DCL as an alternate CLI on either RSX-11M or RSX-11M-PLUS, 
requires only two commands: 


MCR> INSTALL $0CL.TSK/OLT=YES 
MCReCL I /INTTS0CL 
¢ 
When you choose DCL support during system generation, the INSTALL 
command is issued in the SYSVMR portion of system generation. You 
must also include the CLI /INIT command in the system STARTUP.CMD 
file. 


12.2.2 Alternative Ways to Use DCL 


If, for some reason, you choose not to have alternate CLI support, you 
can still use many of the features of DCL by taking advantage of 


alternative ways of installing DCL. You can run DCL as aé_é task, 
install DCL as an external MCR task under the name ...DCL, or install 
DCL as the system catchall task under the name ...CA. 
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If DCL is not a CLI, you cannot log in with the LOGIN command, you 
cannot change your defaults with the SET DEFAULT command, breakthrough 
writes do not break through, and spawned tasks are not renamed (that 
is, a DIRECTORY command spawns a task named PIPTnn, not DIRTnn). 


12.2.2.1 Run DCL as a Task - If you wish, you can simply run DCL as a 
task. If you place the task image file in the system directory on 
RSX-11M or the library directory on RSX-11M-PLUS, users can run DCL 
with the command: 


*RUN $0CL 


DCL runs from your terminal as a task. The terminal remains set to 
MCR. All DCL commands work in the normal way, but a carriage return 
on a line by itself causes the task to exit. 


12.2.2.2 Install as ...DCL - If you install the DCL task as an 
external MCR task under the name ...DCL, users can issue DCL commands 
from an MCR terminal simply by preceding the command with DCL, as in 
the following example: 


MCORS0CL SHOW USERS 


12.2.2.3 Install as ...CA. - If you install the DCL task under the 
name ...CA., all commands) not recognized by MCR are handled by DCL 
running as the catchall task. This means that DCL commands such as 
MOUNT and SET that are identical with MCR commands in the first three 
characters must be in MCR syntax. These commands in DCL syntax are 
recognized by MCR, but only as errors. To avoid infinite loops, the 
DCL installed as MCR's catchall must not be built with MCR as its 
catchall. 


12.2.3 The MCR Command 


The MCR command is included in the default DCL task. This command 
permits users to issue a one-line MCR command without leaving DCL. 
The MCR command is not affected by SET DEBUG. 


Some installations may prefer not to permit DCL users any access to 
MCR. If you wish to restrict access to MCR, you must modify 
DCLBLD.CMD following the instructions contained therein and then 
rebuild DCL. 


12.2.4 DCL SET Commands from MCR 
All DCL SET commands may be used from MCR. MCR has been modified to 


pass all SET commands that do not have a slash in front of the keyword 
to DCL. 
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12.2.5 Allowing Unrecognized Commands to Fall Through to MCR 


The default DCL task returns an error for any command not recognized 
as a DCL command. You may prefer that DCL allow any unrecognized 
commands to fall through to MCR for another chance at execution. This 
permits users direct access to MCR tasks and utilities without using 
the MCR command or the RUN command. 


If you wish to allow commands to fall through DCL to MCR, modify 
DCLBLD.CMD following the instructions contained therein and then 
rebuild DCL. 


12.2.6 Flying Installs 


Tasks need not be installed for DCL to access’ them. Comments in 
DCLBLD.CMD explain how to enable flying installation of tasks. Again, 
modify DCLBLD.CMD and rebuild DCL. 


12.2.7 Task Building DCL 


All of the changes to DCL described in this chapter require that the 
DCL task be rebuilt. The overlay structure of the DCL task forces a 
complex task build that actually requires two passes by the Task 
Builder before it is complete. The first pass creates a symbol table 
(.STB file) that is used by TKB on the second pass to build the DCL 
task. The following two sections summarize the task-build process. 


NOTE 
The file [1,24]DCLBLD.CMD is called by SYSGEN when you 


request DCL support. You should read this file before 
attempting to task build DCL. 


12.2.7.1 Summary of First Task Build - The following summarizes the 
first task build process: 


@ Each DCL command is defined in a parser table (or PT) that 
defines the DCL syntax of the command. 


e The PT is paired with a translator table, or TT, which defines 
the MCR equivalents for the DCL command. 


@ The addresses of the PT and TT are included in a master 
command table (MCT) that lists all DCL commands. 


@ When DCL parses a command, it seeks the address of that 
command in the MCT and then goes to that address for 
translation of the command to MCR at the PT/TT. 


e The parser tables and translator tables are overlaid on the 
master command table; this means that at the time of the first 
task build, the master command table entries are undefined 
symbols. 


The first task build uses a command in the following form: 
TRA 2 DEL. STRENCL 


This results in one or more undefined symbols for each command, but 
the PT/TT addresses for each command are in the .STB file. 
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12.2.7.2 Summary of Second Task Build - The following summarizes’ the 
second task build process: 


e The master command table symbols are defined by means of the 
-STB 


@e The addresses in the PT/TT are doubly defined, once in the 
-STB and once in their overlays. The two definitions are 
identical. In fact, this process is accomplished through two 
-ODL files. See DCLBLD.CMD for more information. 


The second task build uses a command in the following form: 


STKE DCL sfCL=DCL»0CL.STB 


12.2.8 How the DCL Task Works 


This section describes how DCL commands are interpreted and provides 
an overview of how DCL command tables are constructed. 


12.2.8.1 Interpreting DCL Commands - There are three processes 


involved in interpreting DCL commands -- the receive process, the 
parser/translator process, and the send process. The receive process 
gets the command line from the system. The table-driven 


parser/translator process translates the command line to an equivalent 
MCR command line. The send process sends the equivalent MCR command 
line to the system for further interpretation and execution. These 
processes are further described as follows: 


e The receive process involves two tasks: the CLI dispatcher 
task (MCR...) and the DCL task (...DCL). The CLI dispatcher 
task gets the command line from the terminal driver, queues it 
to a CLI queue, and activates the DCL task (if not already 
active). The DCL task activated is named DCLTnn, where nn is 
the number of the issuing terminal. The DCL task (being 
nonprivileged) issues the Get Command for Command Interpreter 
(GCCI$) directive to remove (or receive) the command line from 
the CLI queue. 


e The parser/translator process involves two subprocesses: the 
parser process and the translator process. The parser process 
checks syntax to ensure that the received command line is a 
valid DCL command line. The parser constructs an intermediate 
form (/FORM) to pass data about the command line to the 
translator. The translator process uses this data to 
construct an equivalent MCR command line from the valid DCL 
command line. 


@e The send process dispatches the equivalent MCR command line to 
MCR or MCR utility tasks by means of the Request and Pass 
Offspring Information (RPOI$) directive. The RPOI$ directive 
is functionally similar to the SPWNS directive. There are two 
significant differences from SPWN$: RPOI$ allows the spawned 
task to be named (for example, spawn PIP and name it COPTnn), 
and RPOI$ does not create OCBs (Offspring Control Blocks). 
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The DCL task needs the task-naming ability to track the association 
between the DCL command name and the MCR or utility task that executes 
the command. And, instead of creating an OCB, RPOI$ takes the OCB 
attached to the DCL task and attaches this OCB to the spawned task. 
This enables the spawned task to communicate exit status directly to 
the parent task, DCL. In this way, the DCL task can spawn a task 
without having to wait for the task to exit. 


12.2.8.2 Constructing DCL Command Tables ~- The remainder of this 
chapter describes how to construct the DCL command tables, which drive 
the parser/translator process. Basically, the tables contain the 
following for each DCL command: 


@e The syntax of the DCL command 


e The syntax of the equivalent MCR command (that is, the syntax 
of the MCR command that the DCL command translates to) 


@e The relationship (or mapping) between the DCL syntax and _ the 
MCR syntax. 


MACRO-11 macros and rules define the tables. The macros and rules 
form a language designed to allow the user to express the tables. 


The macros and rules are called the Macro MetaLanguage (MML). Here is 
a list of some of the features of the language and how they are 
employed in the DCL task: 


e MML is modeled after a Backus-Naur Form (BNF) metalanguage. A 
BNF language specifies which sequences of symbols constitute a 
syntactically valid statement in a given language. In this 
case, MML is used to describe the proper syntax of a DCL 
command and the equivalent syntax of an MCR command. 


e MML allows the specification of a prompt string for each 
syntax element. DCL prompts for more input, with the 
specified string, if a test for end-of-line is successful. 


e MML interfaces with the RSX-11M/M-PLUS HELP utility. The user 
requests help by typing a "?" character in reply to a prompt. 


e MML allows the specification of an error message string for 
each syntax element. If DCL detects an error while processing 
a syntax element and that syntax element has a specified error 
message, DCL issues the error message and aborts the parse. 


@ MML allows the specification of contradictory bit masks for 
each syntax element. DCL uses the bit masks’ to detect 
contradictory syntax. 


@ MML allows the use of globally defined syntax elements, such 
as file specifications, device specs, numerals, letters, 
alphanumerics and so forth. 


e MML allows MACRO-11 Assembly Language subroutines to be mixed 


with MML statements in the event that a command cannot be 
completely defined using MML. 
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e@e MML allows one DCL command to translate to more than one MCR 
command. For instance, the DCL SET DEFAULT command can 
generate both an MCR ASN command and an MCR SET /UIC command. 


@e MML supports floating qualifiers. A floating qualifier can be 
specified anywhere in the command line. 


The following section describes the DCL command tables. The DCL 


command tables define all DCL commands and are written in MML. See 
Sections 12.6 through 12.10 for more information on MML. 


12.3 DCL COMMAND TABLES 
The parser/translator process of DCL is table-driven. A master 
command table (MCT) contains an entry for each DCL command. Each 
entry in the MCT contains the following: 

@e The name (verb) of the command 

e The address of a parser table (PT) for the command 


e The address of a translator table (TT) for the command 


e@e The name of the overlay containing the PT and the TT 


(optional) 
Thus, there is a PT and a TT for each DCL command. Each PtT/TT 
contains the information that the parser/translator process needs to 
translate a DCL command line to an equivalent MCR command line. For 


ease in adding and modifying commands, MCT and each PT/TT are kept in 
separate files. 


The file for the MCT is called COMMAND.MAC. The files for the PT/TTs 
are named after the DCL command, with the type .MAC. For example, the 
PT/TT for the DCL COPY command is in a file named COPY.MAC. 


The DCL task uses MCT to recognize an arbitrary command and to locate 
the PT/TT for that command. MCT consists of calls to the COMMAND 
macro. There is a COMMAND macro for each DCL command. Arguments to a 
COMMAND macro specify the name (or verb) of the command, the address 
of the PT for the command, the address of the TT for the command, and 
the overlay name for the command. 


The PT/TTs drive the parser/translator process. The parser/translator 
process ensures that the syntax of the DCL command line is correct and 
creates the /FORM, which is the parser subprocess, and subsequently 
constructs equivalent MCR command lines, which is the translator 
subprocess. The PT drives the parser subprocess and the TT drives the 
translator subprocess. The PT is an MML definition of the syntax or 
structure of the DCL command and the TT is an MML definition of the 
syntax or structure of the corresponding MCR command. 


Table 12-1 shows the structure of the DCL command table files. 


The PT defines the syntax for a DCL command line. The TT defines’ the 
syntax for the corresponding MCR command line. For the translator to 
know which particular MCR command line to construct from a particular 
DCL command line, the PT and the TT must express a relation between 
the DCL syntax and the MCR syntax. 
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Table 12-1 
DCL Command Tables 


COMMAND . MAC ABORT. MAC UNLOCK .MAC 


Master Command Table ABOPT: : UNLPT: : 


Parser 
Table 


Parser 
Table 


COMMAND ABORT ABOPT ABOTT 
COMMAND ASSIGN ASSPT ASSTT 


ABOTT: : UNLTT: : 
- Translator Translator 
Table Table 


COMMAND UNLOCK UNLPT UNLTT 


The PT/TT expresses this relation by mapping elements from DCL syntax 
to elements in MCR syntax. For example, the DCL qualifier "/GLOBAL" 
maps to the MCR switch "/GBL" (that is, the switch "/GBL" is output 
when the qualifier "/GLOBAL" is input). 


The parser passes the mapping information to the translator by means 
of a dynamic data structure called the Intermediate Form (IFORM). The 
parser constructs the IFORM and the translator examines the IFORM. 
The IFORM contains the essential information that the translator needs 
to construct the equivalent MCR command line. Both the PT and the TT 
define the mapping from DCL to MCR syntax. 


The Macro MetaLanguage (MML) defines the PT and the TT. MML is a set 
of MACRO-11 macros and rules implementing a language in which a user 
can define DCL commands. With MML, a user can express the information 
in the PT and the TT in a BNF-type metalanguage. 


The following section describes the structure of the file that 
contains the MCT and of the files that contain the PT/TTs. It also 


describes how these files assemble, overlay, and task build into the 
DCL task. Section 12.4.1.1 describes how to create the PTs and TTs. 


12.4 MODIFYING DCL COMMAND TABLES 

A DCL command consists of an entry in the master command table (MCT), 
a parser table (PT), and a translator table (TT). The PT defines the 
syntax of the DCL command. The TT defines the syntax of the 
corresponding MCR command. The entry in the MCT connects the PT and 


the TT to the DCL task. Thus, to add a new command to the DCL task, 
the user must construct a PT and a TT and make an entry in the MCT. 


12.4.1 Adding Commands 
Adding a command to the DCL task involves the following: 
1. Creating the PT and the TT 


2. Creating the file that contains the PT and the TT 
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3. Making an entry in the MCT 


4. Making an entry in the overlay description file for the DCL 
task 


5. Incorporating the new PT/TT file and the modified MCT file 
into the DCL task 


12.4.1.1 The PT/TT File - The file that contains the PT and the TT is 
named after the verb of the command. The file type is .MAC (for 
example, the PT and the TT for the COPY command are in a file named 
COPY.MAC). The PT/TT file must specify the MACRO-1l assembly 
directives .TITLE, .PSECT, and .END. The title of the file (specified 
as an argument to the .TITLE directive) must also be the same as the 
verb of the command. Normally, the program-section name is _ .CDEF, 
which stands for command definition. If, however, MACRO-11 
subroutines are interspersed with MML notation by means of the S$JSR 
predefined syntax element, the subroutines must be in the blank 
program section. (See Section 12.11 for details on $JSR.) 


In addition to these directives, the pPT/TT file must contain a 
(MACRO-11) global label on the first MML macro of the PT and a global 
label on the first MML macro of the TT. By convention, the label on 
the PT is the same as the verb of the DCL command, and the label on 
the TT is the same as the verb on the corresponding MCR command. The 
following shows the structure of the file that contains the PT and the 
TT for the DCL ASSIGN command: 


ASSIGN .MAC 


-TITLE ASSIGN 
-PSECT .CDEF 


ASSIGN:: 


Parser Table 


Translator Table 


- END 


The two global labels in the PT/TT file connect the PT and the TT to 
the DCL task. This is accomplished by making an entry in the MCT. 


12.4.1.2 The MCT Entry - The file COMMAND.MAC contains the master 
command table (MCT). The MCT consists of a list of (MACRO-11) COMMAND 


macrocalls. Each COMMAND macrocall identifies a DCL command. The 
list of COMMAND macrocalls is ordered alphabetically by the name or 
verb of the command. The COMMAND macro takes five arguments. The 


first four are mandatory and the fifth is optional. The format for 
the COMMAND macro is as follows: 


COMMAND name, min, ptaddr, ttaddr, [ovrnam] 


where: 
name Name or verb of the command 
min Minimum number of characters necessary to make the name 


unique 
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ptaddr Label of the PT for the command 
ttaddr Label of the TT for the command 
fovrnam] Three-character name of the overlay for the PT and TT 


The fifth argument to the COMMAND macro (ovrnam) is optional. The PT 
and TT must, however, be in an overlay whether or not you specify this 
argument. The default overlay name is the command verb, assuming’ the 
PT and TT are in the same module. If they are in separate modules, 
the PT overlay is named for the verb by default, and the TT is’ named 
for the verb preceded by a "T" (for example, TSET.MAC). 


The MCT is in two parts. Part 1 of the MCT includes all DCL command 
verbs in alphabetical order, as described in this section. Part 1 is 
searched with a binary search algorithm. Part 2 of the MCT makes 


possible the brief forms of commonly used DCL commands. If the search 
of Part 1 for a command verb fails -- if a line is too short, for 
instance -- a search of Part 2 is initiated. Part 2 is not 


necessarily in alphabetical order as it is searched from the top down. 


12.4.1.3 The Overlay Entry - Each PT/TT must reside in an overlay. 
Use one of the following structures to overlay a PT/TT: 


@ One overlay for two or more PT/TTs 

@ One overlay for one PT/TT 

@ Two overlays for one PT/TT 

@ More than two overlays for one PT/TT 
Specify an overlay by making an entry in the overlay description files 
-- DCLBLD.ODL and DCDBLD.ODL -- and connect the new overlay entry to 
the root segment overlay entry. 
One Overlay for Two or More PT/TTs 


The format for this overlay entry is as follows: 


- NAME ovrnam 


label: -FCTR ovrnam-DCLO/LB:cmdnaml :cmdnam2...:cmdnamn-L 
where: 
label Connects the entry to the root segment 
ovrnam Three-character name of the overlay 
DCLO Object library containing the modules in the overlays 


cmdnaml Title of the file containing the first PT/TT 


cmdnam2 Title of the file containing the second PT/TT 


cmdnamn Title of the file containing the last PT/TT 
For each entry in the MCT whose command tables (PT/TTs) are in an 


overlay that has two or more PT/TTs, you must include the overlay 
name, Ovrnam. 
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One Overlay for One PT/TT 
The format for this overlay entry is as follows: 


label: .FCTR DCLO/LB:cmdnam-L 


where: 
label Connects the entry to the root segment 
cmdnam Title of the file that contains the PT/TT 


This structure, one overlay and one PT/TT, does not specify the 
overlay name. In this case, the DCL task uses the name or verb of the 
command as the overlay name because the Task Builder default for the 
overlay name is the title of the file. For this reason, the title of 
the file containing the PT/TT must be the same as the name or verb of 
the command. 


Two Overlays for One PT/TT 


The format for this overlay entry is as follows: 


label: .FCTR (DCLO/LB:cmdnam-L, DCLO/LB:tcmdnam-L) 
where: 
label Connects the entry to the root segment 
cmdnam Title of the file that contains the PT 


tcmdnam Title of the file that contains the TT 


Note that this overlay structure, two overlays and one PT/TT, requires 
that the PT and TT reside in separate files. The separate files have 
the same format as a single file that contains the PT/TT except that 
there is only one global label in each file. By convention, the file 
containing the PT is named for the verb of the command and the file 
containing the TT is named for the verb prefixed by "T". The titles 
of the files follow the same convention. For example the file 
containing the PT for the DCL SET command is named SET.MAC with title 
SET, and the file containing the TT for the DCL SET command is named 
TSET.MAC with title TSET. 


More than Two Overlays for One PT/TT 


The format for this overlay entry is as follows: 


label: .FCTR 
(DCLO/LB: cmdnam-L, DCLO/LB:temdnam-L, DCLO/LB:ovrnaml-L) 
where: 
label Connects the entry to the root segment 
cmdnam Title of the file that contains the PT 


tcmdnam Title of the file that contains the TT 
ovrnaml Title of a file containing more parts of the PT/TT 
Basically, the overlay structure of more than two overlays and a 


single PT/TT allows a PT or a TT to invoke additional overlays 
containing additional portions of the PT or TT. Since the PT and TT 
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are read-only data, the additional overlay segments are loaded on top 
of the overlay that is invoking them. On return from the invoked 
overlay, the DCL task reloads the previous overlay. Control returns 
to the point in the previous overlay whence the additional overlay was 
invoked. 


Use the S$CALLOV predefined syntax element to invoke additional 


overlays from a PT or a TT. (See Section 12.11, for details on the 
SCALLOV predefined syntax element.) To specify additional overlays, 
repeat the previous format. That is, for each additional overlay, 


specify an additional argument to the .FCTR directive using the 
format: DCLO/LB:ovrnam-L. 


Next, connect the new overlay entry to the root segment of the DCL 
task by adding the label of the entry to the list of labels for other 
entries. The list of labels for other entries is found in the overlay 
description file after the label OLAY. By convention, enter the 
labels in alphabetical order. The following shows the list of overlay 
entry labels: 


OLAY : sFCTR (11 ,12,13;,14;,15)-<0«,1n) 
where: 
ll,...,ln Labels of overlay entries 


Note that since there are two overlay description files for building 
the DCL task (DCLBLD.ODL and DCDBLD.ODL), you must make new overlay 


entries in both files. The format is the same for both overlay 
description files. For details on how to build the DCL task, see 
Section 12.2. For details on overlay structures, see the 


RSX-11M/M-PLUS Task Builder Manual. 


The last step required to add a command to the DCL task is to 
incorporate all created or modified files into the DCL task, as 
described in the following section. 


12.4.1.4 Incorporating the PT/TT and MCT - The last step in adding 
new commands to DCL -- assembly and task building -- is accomplished 
through the indirect command file [23,24]DCL.CMD, which is on the same 
disk as the DCL sources. This file prompts for the name of a file 


containing the names of all modules you have changed or created. The 
input file consists of one module name per line, with no file type or 
version number. DCL.CMD then assembles the modules, updates’ the 


object libraries, and task builds the new version of DCL. 


Invoke DCL.CMD as follows: 


POEL. 


00 ec went @eesended caommenhke: PY 7p? 


Answer Y to this question. The comments in DCL.CMD direct the 
remainder of the process. 


If all source files assemble correctly, DCL.CMD then builds the DCL 
task. See Section 12.2 for information on how to determine if the DCL 
task was built correctly and for information on how to install DCL as 
a CLI in a multi-CLI environment. 


The DCL.CMD command file is designed to run under MCR with MAC, _ LBR, 
PIP, and TKB installed. DCL.CMD is also designed to run using one 
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UFD: the one that you invoke the command file from. This means’ that 
the following files must be in this UFD: 


@ Specified source files 


e Library files for DCL: DCLO.OLB and DCLR.OLB (the overlay and 
root, respectively) 


e Prefix files for DCL: DCLMAC.MAC and COMMAC.MAC 
e Task-build command file: DCLBLD.CMD 
@e Overlay description files: DCLBLD.ODL and DCDBLD.ODL 


Additionally, RSXMC.MAC must be in LB:[11,10]. Although DCL is 
nonprivileged, DCL needs this file to determine, at assembly time, 
whether your system is RSX-11M or RSX-11M-PLUS. 


12.4.2 Deleting Commands 


To delete a command from DCL, you must break the link between the MCT 
and the PT/TT. To do this, delete the appropriate COMMAND macro entry 
in the MCT, which is in the file COMMAND.MAC. Then, incorporate the 
modified COMMAND.MAC file into the DCL task by following the procedure 
outlined in the preceding section. You can also delete the entry in 
the overlay description files and the object modules for the PT/TT in 
the DCLO.OLB library, but this is optional. 


12.4.3 Modifying Commands 


Modifying an existing DCL command involves modifying the PT/TT files 
to reflect the desired change and incorporating the modified files 
into the DCL task, as described in Section 12.4.1. 


The user defines DCL PTs and TTs using MML. The following section 
describes a metalanguage in general terms, using a simple English 
sentence as the example. Following the introduction of these general 


concepts in Section 12.5 is a more detailed explanation of the Macro 
MetaLanguage (MML) itself in Section 12.6. For instance, the general 
introduction in Section 12.5 includes a description of ANDing and 
ORing in metalanguages, while Section 12.6 describes the AND and OR 
macros of the Macro MetaLanguage. 


12.5 A GENERAL DESCRIPTION OF A METALANGUAGE 


Consider a sentence in the English language. A syntax tree defines 
the structure or syntax of a sentence as shown below: 


<sentence> 
<subject> <predicate> 
[ 
<article> <adjective> <noun> <verb> <direct | object> 
| 
THE OLD MAN WALKED 
<article> <nounl> 

| | 

THE DOG 
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Note that the sentence "The old man walked the dog" is one of many 
sentences that could fit the above structure (syntax). The following 
description of the syntax tree is a metalanguage definition of the 
sentence: 


sentence ::= <subject> <predicate> 
subject ::= <article> <adjective> <noun> 
predicate ::= <verb> <direct object> 
direct object ::= <article> <nounl> 

article ::= THE 

adjective ::= OLD 

noun :3:= MAN 

verb ::= WALKED 

nounl ::= DOG 


Note the equivalence of the metalanguage definition and the syntax 
tree. They describe the same thing. Note also that the metalanguage 


definition uses the symbols "<", ">", and "s:=". 


The symbols "<" and ">" denote category references. These symbols 
enclose the name of the category. Categories define classes of 
objects. For example, the category <subject> defines English words 
that fit the structure of an <article> followed by an <adjective> 
followed by a <noun>. 


The symbol "::=" means "is defined as" and denotes a production rule. 


In a production rule, you specify the category name to the left of the 
"s:=" symbol and the definition for the category to the right of the 

::=" symbol. A category reference means there is a production rule 
for the category that requires that the right part of the production 
rule be substituted for the name of the category. For example, here 
is the production rule for <subject> that references the category 


<adjective>: 
Subject ::= <article> <adjective> <noun> 
The production rule for the category <adjective> is as follows: 
adjective ::= OLD 
Thus, you can rewrite the production rule for <subject> as follows: 
subject ::= <article> OLD <noun> 
Note that you can also substitute further for references to the 
categories <article> and <noun> to produce the production rule as 
follows: 
subject ::= THE OLD MAN 
You cannot substitute for the words: THE, OLD, and MAN. These words 
are literal strings. For simplicity, literal strings are called 
literals, and category references are called nonliterals. A category 


definition (the right part of a production rule) consists of literals 
or nonliterals (or both) concatenated by implied-ANDs. 
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The implied-AND has no symbol in the metalanguage (thus the term 
implied). Use the implied-AND to form category definitions by 
concatenating arbitrary numbers of syntax elements. A syntax element 
is either a literal or a nonliteral. For example, in the category 


definition for <subject> are three nonliterals -- <article>, 
<adjective>, and <noun>. An implied-AND concatenates these 
nonliterals. 


Two additional notations in the metalanguage are as follows: 
Exclusive-OR indicator | 
Optional syntax indicators CJ 

Use the exclusive-OR indicator "|" to show that a category can be 


defined in several ways. For example, here is the production rule for 
the category <adjective>: 


adjective ::= OLD | YOUNG | MIDDLE-AGED 
When substituting for a nonliteral with more than one definition 
(separated by "I"), use only one of the definitions in the 
substitution. For example, substituting for the nonliteral 


<adjective> defined in this way in the production rule for <subject> 
yields one of the following three production rules: 


subject ::= THE YOUNG MAN 
or 
subject ::= THE MIDDLE-AGED MAN 


The square brackets, "[" and "J", enclose optional syntax. For 
example, the following production rule defines the category <subject>: 


subject ::= <article> [ <adjective> ] <noun> 


The square brackets around the nonliteral <adjective> indicate that 
<adjective> is optional syntax. This would allow, by means of 
substitution, rewriting the production rule for <subject> to either of 
the following: 


subject ::= <article> OLD <noun> 
or 
subject ::= <article> <noun> 


In addition to denoting optional syntax, the square brackets also 
indicate iteration. That is, syntax denoted as optional can also be 
used repeatedly to define the syntax. For example, if the following 
defines <adjective>: 

adjective ::= MEAN | OLD | FAT 


you could then rewrite the production rule for <subject> (if <subject> 
is defined with "[" and "]" as above) to the following: 


subject ::= <article> MEAN OLD FAT <noun> 


Note, the repeated substitution for the nonliteral <adjective>. 
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Thus, you can use the symbols, rules, and logic described above as a 
language (that is, as a metalanguage) to define the structure of other 
languages. The structure or syntax of a language is called the 
grammar of that language. The grammar is used to determine 
mechanically whether an arbitrary sentence is a sentence in the 
language. 


Our interest here is in the grammars for DCL and MCR, the 
RSX-11M/M-PLUS command languages. Sentences in these two grammars are 
called commands. Here is a metalanguage definition for the grammar of 
the DCL ASSIGN command: 

assign ::= ASSIGN [ / <qual> ] <device> <device> 


qual ::= LOCAL | LOGIN | GLOBAL | TERMINAL: <device> 


Here is a metalanguage definition for the grammar of the MCR ASN 
command: 


asn ::= ASN <device>=<device> [ / <qual> ] 


qual ::= LOGIN | GBL | TERM= <device> 
The following section describes the Macro Metalanguage (MML). MML 
implements the logic of the metalanguage above. MML defines the 
grammars for the DCL and MCR command languages. Additionally, MML 


expresses the mapping from DCL grammar to semantically equivalent MCR 
grammar. MML provides a more efficient means of generating (by means 
of the MACRO-11 assembler) the data structures that drive the 
parser/translator process than the metalanguage notation. 


12.6 THE MACRO METALANGUAGE 

The Macro MetaLanguage (MML) is a set of MACRO-1ll macros and rules. 
The following describes the correspondence of the metalanguage 
notation presented in the preceding section to MML notation. 


The general metalanguage presented in the preceding section supports 
two logical operators: 


@ implied-AND 
@ exclusive-OR 


The Macro MetaLanguage has two MACRO-11 macros to correspond to these 
logical operators: 


@ AND macros 
@ OR macros 


The general metalanguage presented in the previous section supports 
two types of syntax elements: 


e literals 
e nonliterals 


In MML, literals and nonliterals are presented as arguments to the AND 
and the OR macros. 
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In MML, literals are distinguished from nonliterals by making the 
first character a quote character (for example, 'ASSIGN). An optional 
argument that you can specify with a literal is the abbreviation 
count. The abbreviation count is a numeral that indicates the minimum 
number of characters that the parser needs to match for a_= successful 
parse. For example, you could rewrite 


‘ASSIGN -- to -- <'ASSIGN,4> 


to indicate that the literal "ASSIGN" can be abbreviated to "ASSI". 


NOTE 
The use of the symbols "“<" and ">" indicates (to 
MACRO-11) that the argument "'ASSIGN,4" is one 
argument (not two: ASSIGN and 4). Do not confuse 


these symbols with the identical metalanguage symbols 
used to identify nonliterals. 


In the general metalanguage presented in the previous section, a 
nonliteral is a reference to a category. You define a category with 
the "::=" symbol by specifying the name of the category to the left of 
the symbol and the definition for the category to the right of the 
symbol. 


In MML, you define a category by placing a MACRO-11 label on either 
the AND or the OR macro. The label is the name of the category, and 
the arguments to the macro are the definition for the category. Thus, 
in MML, a nonliteral is the label (of an AND or OR macro) that you use 
as an argument to an AND or OR macro. 


For example, the metalanguage notation for the category <qual> is as 
follows: 


qual ::= GLOBAL | LOCAL | TERMINAL: <device> 
The equivalent MML notation is as follows: 

QUAL: OR 'GLOBAL 'LOCAL TERM 

TERM: AND ‘TERMINAL: S$DEV 


There are two categories: QUAL and TERM. There are three category 
definitions for QUAL: "GLOBAL, ‘LOCAL, or TERM. "GLOBAL and 'LOCAL 
are literals and TERM is a nonliteral. The category definition -- 
"TERMINAL: SDEV -- defines the category TERM, which consists of a 
literal 'TERMINAL and a predefined nonliteral, S$DEV. (See Section 
12.11 for a description of $DEV). 


Note that you must express a category definition like 'TERMINAL: $DEV 
on a separate line (using the AND macro) because an argument to either 
the AND or the OR macro can only represent one syntax 
element. -- either a literal or a nonliteral. 


Use the MML notation "OPT=T" (optional=true) to indicate that syntax 
elements are optional. This notation corresponds to the metalanguage 
notation "{" and "]". The optional syntax notation "OPT=T" is an 
attribute of syntax elements (literals and nonliterals). You 
represent literals and nonliterals in MML notation as arguments to AND 
and OR macros. Therefore, you specify the optional syntax indicator 
“OPT=T" as part of the arguments. 
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To specify "“OPT=T" as an attribute of a syntax element, enclose the 
syntax element and the "OPT=T" notation in angle brackets. For 
example, to specify that the terminal device specification ($DEV) in 
the previous example is an optional syntax element (nonliteral), 
rewrite the category TERM as follows: 


TERM: AND ‘TERMINAL: <$DEV OPT=T> 


Use the "“OPTR=T" attribute to indicate that a syntax element is 
optional and to indicate that the parser/translator can process the 
syntax element repeatedly. 


The notation OPT means a syntax element can occur, at most, one time. 
The notation OPTR means a syntax element can occur many times. In 
either case, the element can occur zero times. For a complete 
description, see Section 12.10. 


To specify an arbitrary number of arguments for the AND and OR macros, 
use the OR., AND., and the END macros. Use the AND. andOR. macros 
as continuation markers for the AND and OR macros respectively. That 
is, if there is not enough space on the line for all the arguments to 
either the AND or OR macros, place additional arguments on the next 
line. To do this, place the AND. or the OR. macro on the next line 
followed by the continuation of the specification of the arguments. 
For example, you could rewrite the category for <qual> to the 
following: 


QUAL: OR ‘GLOBAL 'LOCAL 
OR. TERM 
END 


Use the END macro to indicate the end of the specification of the 
arguments. Note, to allow this continuation ability (without any 
additional overhead), you need the END macro whether or not you use 
the continuation ability. For example, you would need the END macro 
in the following category for <qual>: 


QUAL: OR 'GLOBAL 'LOCAL TERM 
END 


Thus, you can use MML like the metalanguage of the general description 
in Section 12.5 to define the syntax of a DCL command and the syntax 
of the corresponding MCR command. The parser table (PT) defines the 
syntax of the DCL command and the translator table (TT) defines the 
syntax of the corresponding MCR’ command. The following section 
describes how the PT and TT drive the parser/translator process (or 
how the parser and the translator interpret the PT and the TT). 


12.7 INTERPRETING DCL COMMAND TABLES 


A parser table (PT) and translator table (TT) drive the 
parser/translator process. There is a PT/TT for each DCL command. 
The PT defines the DCL syntax and the TT defines the corresponding MCR 
syntax. The parser/translator process locates the PT and the TT for a 
particular DCL command line by searching the master command table 
(MCT) for the command entry. The parser/translator extracts from the 
command entry the address of the first AND or OR macro of the PT and 
the address of the first AND or OR macro of the TT. 
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12.7.1 Parser Processing 


The parser starts processing at the address of the first macro in the 
PT. If the processing of this macro succeeds, then the parser process 
succeeds. A successful parser process means that, at this point, the 
input command line is a syntactically correct DCL command line (as 
defined by the PT) and the intermediate form (IFORM) has_- been 
constructed. The IFORM is’ a condensed representation of the input 
command line. If the processing of this macro fails, then the parser 
process fails. 


The parser processes the AND macro by processing (left-to-right) each 
argument (syntax element) of the AND macro until either all arguments 
process successfully or an argument is encountered that does not 
process successfully. If all arguments process successfully, then the 
processing of the AND macro succeeds; otherwise, the processing of the 
AND macro fails. 


The parser processes the OR macro by processing (left-to-right) each 
argument (syntax element) of the OR macro until either the parser 
successfully processes one syntax element or the parser fails to 
process any of the syntax elements. If the parser successfully 
processes one syntax element, then the processing of the OR macro 
succeeds; otherwise, the processing of the OR macro fails. 


12.7.2 Translator Processing 


The translator starts processing at the address of the first macro of 
the TT. If the processing of this macro succeeds, then the 
translation succeeds and an equivalent MCR command line (as defined by 
the TT) has been constructed from the IFORM. If the processing of 
this macro fails, then the translator process fails. The processing 
of the AND and OR macros by the translator is the same as the 
processing of the AND and OR macros by the parser (as described in the 
previous section). 


Arguments to AND and OR macros can be literals or nonliterals. 
Nonliterals are handled in the same way by both the parser and the 
translator. Literals, however, are handled differently by the parser 
and the translator. 


12.7.3 Parser/Translator Handling of Nonliterals 


Here is a description of how nonliterals are handled by both the 
parser and the translator. 


In MML, when you use the label of an AND or OR macro as the argument 
to an AND or OR macro it is called a nonliteral; thus, a nonliteral is 


the address of another AND or OR macro. The processing of a 
nonliteral is the processing of the other AND or OR macro that the 
nonliteral addresses. That is, when the parser or translator 


encounters a nonliteral (as an argument to an AND or OR macro), the 
parser or translator transfers parsing or translation control to _ the 
macro that the nonliteral addresses. The addressed macro is either an 
AND or OR macro and the parser/translator processes this macro like 
all AND or OR macros (as described in the previous section). If the 
processing of this macro succeeds, then the processing of the 
nonliteral succeeds; otherwise the processing of the nonliteral fails. 
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12.7.4 Parser/Translator Handling of Literals 


Here is a description of the different handling of literals by the 
parser and the translator. 


A string of ASCII characters used as an argument to an AND or OR macro 
is called a literal. The string typically is a keyword in the DCL or 
MCR command grammar. The parser and translator process literals 
differently. 


In parsing a literal, the parser attempts to match the literal to the 
input DCL command line. If the input command line contains the same 
ASCII string as the literal, then the match is successful and the 
processing of the literal succeeds; otherwise, nothing happens. 


However, in translating a literal, the translator copies the literal 
from the TT to the MCR command line buffer. If you do not associate 
attributes with a literal in a TT, then the processing of the literal 
always succeeds. (Writing a literal to the MCR command line buffer 
always succeeds.) A literal in a TT can fail only if you have 
associated one of the following attributes with the literal: 


MAP, CBM, BCT, BST 


With these attributes associated with a literal, the translator 
processes the attributes before the literal is written to the MCR 
command line buffer. 


The MAP attribute instructs the translator to check for a mapping 
number in the IFORM. If the number is not there, the translator does 
not write the literal to the MCR command line buffer and the 
processing of the literal fails. 


The CBM, BCT, and BST attributes instruct the translator to check the 
status of certain bits in its internal data structures. If the status 
of the bits is not correct, the translator does not write the literal 
to the MCR command line buffer and the processing of the literal 
fails. (See Section 12.10 for more information on these attributes). 


12.7.5 Summary of Parser/Translator Functions 


In summary, the parser table (PT) drives the parser and the translator 
table (TT) drives the translator. The parser/translator succeeds only 
if the processing of the first AND or OR macro of the PT/TT succeeds. 
The processing of an AND or OR macro succeeds only when the processing 
of the arguments to the macros’ succeed. Arguments can be either 
literals or nonliterals. A nonliteral instructs the parser/translator 
to process (recursively) another AND or OR macro and succeeds only if 
the subsequent AND or OR macro succeeds. A literal instructs the 
parser to ensure the input command line matches the literal and 
succeeds only if the match is successful. A literal instructs the 
translator to output the literal (possibly conditionally) to the MCR 
command line and the translator succeeds only if either the literal is 
not conditionalized or the conditionals are satisfied. 
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12.7.6 Examples 


The following is an example of a parser table (PT) for the DCL ASSIGN 
command. 


MML NOTATION for PARSER TABLE 


ASSIGN:: AND "ASSIGN <QUAL OPTR=T> SDEV SDEV 
END 
QUAL: AND '/ QUALI 
END 
QUALI: OR <'LOCAL, 4> 
OR. <'LOGIN, 4> 
OR. <'GLOBAL, 2> 
OR. TERM 
END 
TERM: AND "TERMINAL: <'TERMINAL,4>': 
END 


The following is an example of a translator table (TT) for the MCR ASN 
command. 


MML NOTATION for TRANSLATOR TABLE 


ASN:: AND ‘'ASN SDEV '= SDEV <LAUQ OPTR=T> 
END 
LAUQ: OR ' /LOGIN 
OR. ' /GBL 
OR. MRET 
END 
MRET: AND '/TERM= SDEV 
END 


These examples show the first two steps you must follow in creating 
the tables for the DCL ASSIGN command. The last step is to express 
the mapping of the syntax elements in the PT to the syntax elements in 


the TT. This mapping provides the information that the 
parser/translator process needs to construct a particular MCR ASN 
command line given a particular DCL ASSIGN command line. The 


following section describes how to express this mapping. 


12.8 MAPPING DCL TO MCR 


The mapping of a given DCL command line to the equivalent MCR command 
line is accomplished in the IFORM. The parser processes mapping 
information and records it in the IFORM. The translator searches’ the 
IFORM for mapping information and then generates the MCR command line. 


Mapping information is expressed in MML with the "MAP=n" attribute. 
MAP takes one or two values. The first value is called the primary 
mapping number. The second value is called the secondary mapping 
number. If you need only the primary mapping number, specify it in 
the following form: 


MAP=n 
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If you need to specify both mapping numbers, which is allowed only in 
a TT, or if you need to specify only the second number, then enclose 
the numbers in angle brackets and separate them with a comma in the 
following form: 


MAP=<n,n> or MAP=<,n> 


To associate the MAP attribute with a syntax element, enclose the 
syntax element and the MAP attribute in angle brackets as follows: 


<syntax-element MAP=n> 


To map a DCL syntax element in a PT to an MCR syntax element in the 
corresponding TT, use MAP with the same mapping number for both syntax 
elements. 


For example, in the ASSIGN command, the DCL qualifier "/GLOBAL" maps 
to the MCR qualifier "/GBL". That is, when the DCL qualifier 
"/GLOBAL" is input (as part of the DCL command line), the MCR switch 
"/GBL" is output (as part of the MCR command line). 


The following expresses this mapping in MML notation and illustrates 
the use of the primary MAP number. 


QUAL: OR <'/GLOBAL MAP=1> ... 


END 
LAUQ: OR <'/GBL MAP=1> ... 
END 
MML macros at QUAL: define DCL syntax. MML macros at  LAUQ: (QUAL 


spelled backwards) define the corresponding MCR syntax. When the 
parser reaches QUAL:, it tries to match the literal "/GLOBAL" to the 


input (DCL) command line. If the match is successful, then the parser 
queues the MAP number "Pl" (the "P" indicates a primary mapping 
number) to the IFORM queue. When the translator reaches LAUQ:, it 
searches the IFORM queue for the MAP number "Pl". If the translator 
finds the MAP number "Pl", it outputs to the (forming) MCR command 
line the literal "/GBL". If the translator cannot find the MAP number 
in the IFORM queue, it does not use the syntax element (associated 


with the MAP number) in the translation. 


The MAP attribute in a PT can associate either a primary or a 
secondary mapping number with a syntax element, but not both. 
However, the MAP attribute in a TT can associate either or both 
mapping numbers with a syntax element. 


Associating a primary mapping number with a syntax element in the PT 
(by means of the MAP attribute) instructs the parser to queue the 
primary mapping number to the IFORM queue. Associating a secondary 
mapping number with a syntax element in the PT instructs the parser to 
queue the secondary mapping number to the IFORM queue. In both cases 
the parser queues a mapping number only if the parser processes the 
associated syntax element successfully. 


The MAP attribute in a TT instructs the translator to search the IFORM 


queue for a mapping number. When found, the translator marks the 
mapping number used and processes the associated syntax element. 
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The search for a primary mapping number differs from the search for 
secondary mapping numbers. The translator searches the entire IFORM 
queue from head to tail to find.- primary mapping numbers. The 
translator limits its search for secondary mapping numbers, however. 
The translator starts its search for secondary mapping numbers at’ the 
queue element containing the last used primary mapping number and 
stops the search at the next queue element containing a primary 
mapping number. 


Specifying both a primary and a secondary mapping number in the TT 
(for example, MAP=<1l,l1>) instructs the translator to search the entire 
IFORM queue for the specified primary mapping number such that the 
specified secondary mapping number follows without any intervening 
primary mapping numbers. The secondary mapping number qualifies the 
primary mapping number. The primary mapping number is the object of 
the search. 


If the translator finds a mapping number in the IFORM queue, the 
translator processes the associated syntax element. If the translator 
fails to find the mapping number, the processing of the associated 
syntax element fails. When the translator finds a mapping number and 
successfully processes the associated syntax element, the translator 
marks as used the queue element containing the found mapping number. 
A used mapping number can no longer be found. This prevents infinite 
loops in the TT without requiring the specification of termination 
conditions. 


A MAP attribute can be specified in both the PT and the TT without 
associating it with a syntax element, as follows: 


<MAP=n> 


If you specify this attribute as an argument to an AND or OR macro in 
a PT, the parser assumes a null syntax element. A null syntax element 
always succeeds. 


If you specify a null syntax element in a TT, the translator (after 
finding the queue element containing the mapping number) checks to see 
if a character buffer is attached to the queue element. If a 
character buffer is attached, then the translator copies the contents 
of the buffer to the MCR command line buffer. If a character buffer 
is not attached, then the translator (like the parser) assumes a null 
syntax element (which always succeeds). 


The parser attaches the character buffer to the queue element. The 
COP attribute instructs the parser to create the character buffer and 
copy the text parsed by the associated syntax element to the character 
buffer (See Section 12.10 for details on the COP attribute). 


Thus, mapping starts in the parser process when the parser queues 
mapping numbers to the IFORM queue, as it successfully processes 
syntax elements that have associated MAP attributes. 


Mapping is completed in the translator process when the translator 
detects mapping numbers in the IFORM queue and translates the syntax 
elements. Note that the translator does not output a syntax element 
that has a MAP attribute associated with it unless (1) the translator 
first finds the mapping number in the /FORM queue, and (2) the mapping 
number has not been previously used. 
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Here is an example of a complete command table (with DCL-MCR mapping) 
for the DCL ASSIGN command: 


ASSIGN MML NOTATION FOR PARSER TABLE 


ASSIGN:: AND ‘ASSIGN <QUAL OPTR=T> <SDEV MAP=1> <SDEV MAP=2> 
END 
QUAL: AND '/ QUALI 
END 
QUALI: OR <'LOCAL, 3> 
OR. <'LOGIN,3 MAP=3> 
OR. <'GLORAL, 2 MAP=4> 
OR. TERM 
END 
TERM: AND <'TERMINAL,4>' <DEV MAP=5> 
END 


ASN MML NOTATION FOR TRANSLATOR TABLE 


ASN:: AND ‘ASN <MAP=1> '= <MAP=2> <LAUQ OPTR=T> 
END 
LAUQ: OR <'/LOGIN MAP=3> 
OR. <'/GBL MAP=4> 
OR. MRET 
END 
MRET: AND '/TERM= <MAP=5> 
END 


For a complete description of the MAP attribute, see Section 12.10. 
For information on related attributes see the discussions of the 
following: 


DMAP, NO, COP, OCOP, TST, and DIR 


The parser records mapping information; the translator detects’ the 
mapping information. The following section presents IFORM, the 
dynamic data structure that passes mapping information from the parser 
to the translator. 


12.9 THE INTERMEDIATE FORM (IFORM) 


The IFORM contains the essential information (extracted from the input 
DCL command line) that the translator needs to construct the MCR 
command line. The IFORM consists of three data structures: the 
queue, the character buffers, and the general bit-mask words. 


NOTE 


To display the IFORM for a given DCL command, use SET 
DEBUG/FULL. 


The parser creates the IFORM queue when it successfully processes 
syntax elements with MAP attributes. Each time the parser 
successfully processes a MAP attribute, it queues the mapping number 
to the IFORM queue. 


The parser creates a character buffer when a syntax element has both 
MAP and COP attributes. The parser attaches the character buffer to 
the queue entry that contains the mapping number. The character 
buffer contains the text parsed during the processing of the 
associated syntax element. 
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A syntax element with a COP attribute and no MAP attribute instructs 
the parser to copy the text parsed to the last queued mapping number 
(creating and attaching the character buffer if neccessary). 


The general bit-mask words are two words used as a set of 32 flags. 
The parser/translator process attaches no meaning to the flags, but 
MML provides a set of attributes to set flags, clear them, test if the 
flags are set, and test if the flags are clear. You can use the flags 
to check for contradictory syntax. In addition, use the flags to pass 
information from the parser to the translator. For example, set a 
flag during the parser process if a DCL qualifier is seen and detect 
the set flag during the translator process, generating the equivalent 
MCR switch. 


The translator searches the IFORM queue for mapping numbers. If the 
translator finds the mapping numbers, it processes the syntax 
elements. If the translator cannot find the mapping numbers, then the 
syntax elements fail. 


If a MAP attribute is specified without an associated syntax element 
as follows: 


<MAP=n> 


the translator first finds the queue element containing the mapping 
number and then examines the queue element for a character buffer 
attached by means of the COP attribute. If the translator finds an 
attached character buffer, it copies the contents of the buffer to the 
MCR command line buffer. If the translator cannot find an attached 
buffer, it assumes a null syntax element (which always succeeds). 


Use the following attributes (in the PT) to direct the parser in the 
creation of the IFORM: 


MAP=n MAP=<,n> (map ) 

DMAP=n DMAP=<,n> (map unless duplicate exists) 

COP= OCOP=T (copy, or copy optional input) 

BS=n BS=<,n> BS=<n,n> (set bit in mask word) 

BC=n BC=<,n> BC=<n,n> (clear bit in mask word) 

NO= (repeats for negative form of 


syntax element) 


Use the following attributes (in the TT) to direct the translator in 
the examination of the IFORM: 


MAP=n MAP=<,n> MAP=<n,n> (unmap) 

BST=n BST=<,n> BST=<n,n> (test for bit set in mask word) 
BCT=n BCT=<,n> BCT=<n,n> (test for bit clear in mask word) 
TST=T (test for mapping number, do not 


mark as used) 
DIR=T (search IFORM in reverse direction) 


For details on these attributes, see Section 12.10. 
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For example, if the input command line is: 
ASSIGN DKl: SY: 
then the IFORM would be: 


Queue Character Buffer 


Pah | sae 
ee 


If the input command line is: 


ASSIGN/LOGIN/T:TT12: DKl: SY: 
then the IFORM would be: 


Queue Character Buffer 


12.10 ATTRIBUTES OF SYNTAX ELEMENTS 


Attributes associate characteristics with literal and nonliteral 


syntax elements. The parser/translator processes attributes either 
before or after it processes the associated syntax elements (depending 
on the attribute). The processing of attributes can influence the 


processing of the associated syntax elements. 


Here is the format for specifying attributes as part of an argument to 
an AND or OR macro: 


<'literal KEY=value KEYl=value ...> 
or 

<label KEY=value KEYl=value ...> 
where: 

literal Literal (ASCII) string 

label Nonliteral (address of an AND or OR macro) 

KEY Attribute keyword identifying the attribute 

value Value assigned to the attribute 
Note the use of the angle brackets "<" and ">". Use these MACRO-11 
symbols to indicate that everything enclosed is considered as one 
argument (when expanding macros). Do not confuse these MACRO-11 angle 


brackets with the angle brackets used to indicate nonliterals in 
metalanguage notation. 
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12.10.1 AND 
AND allows you to extend a syntax element by specifying a nonliteral 
that is ANDed to the syntax element. The primary function of AND is 
to allow OR logic to be mixed with AND logic. Assign a nonliteral to 
the AND attribute as follows: 

AND=label 
where: 

label Nonliteral address of an AND or OR macro 
AND instructs the parser/translator to process the AND or OR macro 
that the label (the nonliteral) addresses in addition to processing 


the syntax element with which the AND attribute is associated. 


For example, in the following MML definition for QUAL, the second 
syntax element defines the structure "FILE:<filespec>": 


QUAL: OR "BRIEF 
OR. <'FILE AND=FNAME> 
OR. ‘FULL 
END 
FNAME: AND ‘': SFILE 
END 


There are three syntax elements in this structure: 


FILE 
and 
and 
<filespec> 
The literal ":" and the nonliteral <filespec> connect to the literal 


"FILE" by means of the AND attribute. The parser/translator processes 
all three elements as one element to the OR macro by definition of the 
AND attribute. 


12.10.2 BC and BS 


BC (Bit Clear) and BS (Bit Set) operate on two global bit-mask words 
as follows: 


@ The BC attribute instructs the parser/translator to clear bits 
in these two global words. 


e The BS attribute instructs the parser/translator to set bits 
in these two global words. 


Use the BCT and BST attributes to test these bits. (See the next 
section. ) 


The format for these attributes is as follows: 
BC=n or BC=<,nl> or BC=<n,nl> 


BS=n or BS=<,nl> or BS=<n,nl> 
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where: 
n Bit mask specifying bits in the first glohal word 
nl Bit mask specifying bits in the second global word 


Specify a bit mask by ORing single bit specifications with the 
MACRO-11 symbol "I". The symbols Bl, B2,...B32 are predefined to 
correspond to single bit specifications for each bit in the two global 
words. 


For example, BS=B1!B2!B5 means to set bits 1, 2, and 5 of the first 
global word. See the next section for an example of these attributes 
in use. 


12.10.3 BCT and BST 


BCT (Bit Clear Test) and BST (Bit Set Test) test the status of bits in 
the two global bit-mask words as follows: 


@e The BCT attribute instructs’ the parser/translator to test 
whether bits are cleared. 


e The BST attribute instructs the parser/translator ,to test 
whether bits are set. 


See the previous section for information on how these bits are set or 
cleared. The parser/translator does not clear the two global bit-mask 
words between the parse and the translation. You can use these words 
as part of the IFORM to pass information from a PT to a TT. . 


The format for these attributes is as follows: 


BCT=n or BCT=<,nl> or BCT=<n,nl> 
BST=n or BST=<,nl> or BST=<n,nl> 
where: 
n Bit mask specifying bits in the first global word 
nl Bit mask specifying bits in the second global word 


For example, BST=<,B19!B31> means to test whether bits 19 and 31 of 
the second global bit-mask word are set. 


The following example illustrates the use of BS, BC, BST, and BCT: 


COPY: AND FILE <FILE OPTR=T> QUA=QUAL 
END 

FILE: OR <SNFIL BS=Bl BCT=B2!B3> 
OR. SFILE 
END 

QUAL: OR <' INDEX BS=B2 BCT=B1 !B3> 
OR. <' SEQUENTIAL BS=B3 BCT=B1!B2> 
END 


In this example, INDEX and SEQUENTIAL are qualifiers, S$NFIL is a 
predefined syntax element that is a file specification that has a node 
name prefixing it, and $FILE is a predefined syntax element that is a 
conventional file specification (without a node name). The example 
specifies that the qualifiers INDEX and SEQUENTIAL are contradictory, 
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that INDEX and SNFIL are contradictory, that SEQUENTIAL and $NFIL are 
contradictory, but that duplicates of each are not contradictory. The 
BS attribute instructs the parser to set the specified bits if the 
processing of the associated syntax elements is successful. The BCT 
instructs the parser to test whether the specified bits are clear. 


If the tested bits are set, the parser does not process the associated 
syntax elements. Thus, bits are set to remember which syntax elements 
process successfully, and bits are tested to determine if a 
contradiction would result from the processing of syntax elements. 


The main difference between the BC, BCT, BS, and BST attributes and 
CBM (described in the next section) is that CBM always prevents 
duplicate syntax as well as contradictory syntax, but CBM cannot pass 
information from the parser to the translator. 


12.10.4 CBM, CCBM 


Use CBM (Contradictory Bit Mask) to prevent the parser or translator 
from allowing contradictory syntax. To indicate that two or more 
syntax elements cannot be specified in the same command line, specify 
CBM with each syntax element. Assign a bit mask as the value to CBM. 
Specify the same bit in each bit mask associated with each 
contradictory syntax element. 


CBM conditionalizes the processing of the associated syntax element. 
The parser uses the specified bit mask to set bits in two global 
words. If the parser detects that any bits specified in the bit mask 
are already set in the two global words, then the parser assumes a 
contradiction and the syntax element fails. This also means CBM does 
not allow duplicate syntax elements. 
Also note that the parser/translator clears the two global words 
between the parse and the translation. You cannot use CBM to pass 
information from a PT to a TT. 
The format of the CBM attribute is as follows: 

CBM=n or CBM=<,nl> or CBM=<n,nl> 
where: 

n Bit mask specifying bits in the first global word 


ni Bit mask specifying bits in the second global word 


Specify a bit mask by ORing single bit specifications with the 


MACRO-1ll symbol "!". The symbols Bl, B2,..., B32 are predefined to 
correspond to single bit specification. For example, CBM=B1!B2!B5 
specifies bits 1, 2, and 5 of the first global word, and 


CBM=<,B19!B31> specifies bits 19 and 31 of the second global word. 


The following example illustrates the use of the CBM attribute: 


QUAL: OR <' LOCAL CBM=B1 ! B2> 
OR. <'LOGIN CBM=B2> 
OR. < 'GLOBAL CBM=B1 > 
END 


The example specifies that the literals "LOCAL" and "GLOBAL" are 
contradictory, and that the literals "LOCAL" and "LOGIN" are also 
contradictory, but that the literals "LOGIN" and "GLOBAL" are not. 
The example also specifies that each of these elements can be used 
only once. 
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CCBM (Clear Contradictory Bit Mask) clears the bits in the two global 
words. The format for specifying CCBM is identical to the format that 
you use to specify the CBM attribute. 


12.10.5 COP, OCOP 


COP (COPy) is legal only in a PT and only with a literal syntax 


element. COP passes a literal from the input DCL command line to the 
IFORM. The translator can then use the literal in the MCR - command 
line. The parser copies the literal to a character buffer and 


attaches it to the mapping number last queued. If you specify a MAP 
attribute with the COP attribute, the mapping number (assigned to the 
MAP attribute) is the mapping number last queued. The format of the 
COP attribute is as follows: 


COP=T 
For example, the following code defines a terminal specification: 


TERM: OR <'TT COP=T AND=N> 
OR. <'HT COP=T AND=N> 
OR. <'VT COP=T AND=N> 
OR. <'TI COP=T AND=N> 
END 
N: AND <SONUM,0,3> <': OCOP=T> 


This code parses and copies a terminal name as TT, VT, HT, or TI 
followed by an octal number as terminal names. (See Section 12.11.1 
for a description of S$ONUM, which defines an octal number.) The OCOP 
attribute assures the presence of the terminating colon by copying it 
into a character buffer whether or not the user inputs one. 


To instruct the translator to copy the character buffer to the MCR 
command line, specify the MAP attribute as follows, without specifying 
an associated syntax element: 


<MAP=n> 


When the translator processes a MAP attribute that has no associated 
syntax element, the translator examines the mapping number queue 


element for an attached character buffer. If a character buffer is 
found, the translator copies the contents of the character buffer to 
the forming MCR command line buffer. If a character buffer is not 


found, the translator assumes a null syntax element (which always 
processes successfully). 


OCOP (Optional COPy) is identical to COP except for one significant 
difference. OCOP instructs the parser to copy the literal to the 
IFORM whether or not the processing of the literal succeeds. That is, 
the literal is optional and always succeeds if you associate OCOP with 
Le 
The following illustrates the use of the OCOP attribute: 

DEV: AND <SALF,2,2> <SNUM,0,3> <': OCOP=T> 
The MML definition defines a device specification such that the colon 
on the end of the specification is optional. The translator copies 


the colon to the output MCR command line whether or not the parser 
found a colon in the input DCL command line. 
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12.10.6 DIR 


DIR (DIRection) is legal only in the TT and only when you specify it 
with a MAP attribute. DIR instructs the translator to search the 
IFORM queue for the specified mapping number in reverse order. The 
normal direction of the search is from the head of the queue to the 
tail of the queue. DIR instructs the translator to search the IFORM 
queue from the tail to the head of the IFORM queue. The format for 
DIR is as follows: 


DIR=R 


The following example of a TT fragment illustrates the use of the DIR 
attribute: 


FILE: AND <MAP=1 DIR=R <MORE OPT=T> 
END 
MORE : AND <<',>> FILE 
END 
This example defines (recursively) the structure of a file 


specification list, where the file specifications are mapped to 
mapping number 1. Due to the associated DIR attribute, the translator 
searches for the mapping numbers in reverse order; thus, the list of 
file specifications is output to the MCR command line in reverse 
order. 


NOTE 
The double angle brackets are necessary in cases where 
the contents of the brackets include a MACRO-11 


separator character (in this case, the comma) that is 
to be treated as a literal by MML. 


12.10.7 ERR 
ERR (ERRor) allows you to associate error messages with syntax 
elements. If the parser or the translator fails to process a syntax 
element, and the syntax element has ERR specified, then the parser or 
translator prints the error message specified and aborts the parse or 
translation. The format for ERR is as follows: 

ERR='string 

or 
ERR=label 
label: ERROR </string/> 

For example, to specify an error message for the device being 
assigned, use the following MML notation in the PT for the ASSIGN 


command: 


AND "ASSIGN <QUAL OPT=T> <$DEV ERR=<'Invalid device>> 
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If the parser cannot parse the input DCL command line text that 
corresponds to the device specification ($DEV), the parser prints the 
message "ASSIGN -- Invalid device", and aborts the parse. 


12.10.8 HLP 


Use HLP (HeLP) in a PT only to associate help text with syntax 
elements that have the PRO attribute (Section 12.10.12) specified. 
When the parser is prompting and a "?" character is input, the parser 
spawns a HELP command. The parser appends the text specified in the 
HLP attribute to the HELP command "HELP command" where "command" is 
the name of the DCL command being processed. The format of the HLP 
attribute is as follows: 


HLP='string 
or 
HLP=label 
label: HELP </string/> 
where: 
string Appended to the HELP command 
label Label of a HELP macro 


The parser appends the string to the command "HELP command", where 
"command" is the name of the current command being processed. For 
example, if you specify the PT for ASSIGN as: 


AND <QUAL OPTR=T> <SDEV PRO='Device? HLP=<'Logical name>> 


and the user types a "?" in response to the prompt "Device?", the 
parser forms and spawns the command "HELP ASSIGN LOGICAL NAME". 


This requires a file named DCLASSIGN.HLP containing the necessary help 
text: For the format of the HELP file, see the HELP documentation in 
the RSX-11M Command Language Manual, the RSX-11M-PLUS Command Language 
Manual or the RSX-11M/M-PLUS MCR Operations Manual. 


12.10.9 MAP, DMAP 


MAP is legal in both the PT and the TT. However, the parser and _ the 
translator interpret MAP differently. The following summarizes the 
types of legal MAP attributes in a parser table: 


MAP=n Instructs the parser to queue the specified primary 
mapping number n to the IFORM queue only if the 
associated syntax element is successfully parsed. 


MAP=< ,nl1> Instructs the parser to queue the specified secondary 
mapping number nl to the IFORM queue only if the 
associated syntax element is sucessfully parsed. 


Note that specifying COP with MAP ina PT instructs the parser to 
create and attach a character buffer to the mapping number, and copy 
the text parsed by the associated syntax element to the attached 
character buffer. For additional details, see Section 12.10.5, which 
describes COP. 
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The following summarizes the types of legal MAP attributes in a 
translator table: 


MAP=n Instructs the translator to search the IFORM queue 
from top to bottom for the specified primary mapping 
number n. If found, the translator places the element 


in the MCR command line. If not found, nothing 
happens. 

MAP=<,nl1> Instructs the translator to search the IFORM queue for 
the secondary mapping number nl. Because the object 


of the search is a secondary (not primary) mapping 
number, the translator does not search the entire 
IFORM queue. The translator starts searching at the 
last used primary mapping number and stops the search 
at the next primary mapping number. If the secondary 
mapping number is’ found, then the associated syntax 
element is processed; otherwise, nothing happens. 


MAP=<n,nl> Instructs the translator to search the IFORM queue 
from head to tail for the specified primary mapping 
number n. If found, the translator searches for the 
specified secondary mapping number nl. If found, the 
associated syntax element is processed. If not found, 
another occurrence of primary mapping number n is 
sought. If another instance of primary mapping number 
n is found, then the translator looks again for the 
specified secondary number nl. This search process 
continues until either all primary mapping numbers n 
have been found and none of them have a_ secondary 
mapping number nl after them, or until a primary 
mapping number n is found that does have a_e secondary 
mapping number nl after it. 


If you specify a MAP attribute in a TT without specifying an 
associated syntax element, the translator examines the queue element 
containing the specified mapping number for an attached character 


buffer. If the translator finds an attached character buffer, the 
translator copies the contents of the buffer to the forming MCR 
command line buffer. If the translator does not find an attached 


character buffer, the translator assumes a null syntax element (which 
always processes successfully). 


To allow additional flexibility in the search for secondary mapping 
numbers, the translator supports the following additional formats for 
specifying the MAP attribute in a TT: 


MAP=<X,nl> Instructs the translator to search the IFORM queue 
from head to tail for the specified secondary mapping 
number nl. If found, the translator processes’ the 
associated syntax element. If not found, the 
associated syntax element fails to _ process. The 
keyword "X" identifies this MAP attribute as an 
unconditional search for a secondary mapping number. 


MAP=<X1,n1> Instructs the translator to seach the IFORM queue for 
the secondary mapping number nl. The keyword "X1" 
instructs the translator to limit the search of the 
queue as follows. The search is started at the head 
of the queue and proceeds until the first primary 
mapping number is detected. If the secondary mapping 
number nl is not found, then another search is 
conducted. The second search looks for the secondary 
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Mapping number nl such that it follows a negative 
primary mapping number. If found, the translator 
processes the associated syntax element. If not 
found, nothing happens. 


Note that you use the "X" MAP attribute to search for a secondary like 
a primary (that is, unconditionally) and the "Xl" MAP attribute to 
search for floating command qualifiers. For information on floating 
command qualifiers see Section 12.10.13, which describes QUA. 


When the translator finds a mapping number and processes the 
associated syntax element, the translator marks the mapping number as 
used. A used mapping number cannot be found again by the translator. 
Thus marking mapping numbers used prevents infinite loops in the TT 
without the need to specify termination conditions. To override the 
marking of mapping numbers, use TST. To reset all marked mapping 
numbers, use the $RESET predefined syntax element. (This is useful 
for generating multiple MCR commands by means of the SNEW predefined 
syntax element.) 


DMAP (duplicate map) is identical to MAP in most ways. However, it is 
only allowed in a PT. DMAP instructs the parser not to queue the 
mapping number to the IFORM queue if the same mapping number is 
already present in the IFORM queue. If the parser does not queue the 
mapping number, then the syntax element that MAP is associated with 


fails to process. Thus, the DMAP attribute can prevent duplicate 
syntax. 
For additional information on the use of the MAP attribute, see the 


Section 12.8, Mapping DCL to MCR. 


The following example shows the use of primary mapping numbers with 
predefined syntax elements. 


DCL file specifications, device specifications, numerals, and _ so 
forth, map to themselves. That is, when a file specification, device 
specification, numeral, and so forth, is input, the same file 


specification, device specification, numeral, and so forth, is output. 
Here is an example of how a terminal device specification maps to 
itself. 


Parser Table 


TERM: AND 'TERMINAL: <SDEV,MAP=2> 
END 


Translator Table 


MRET: AND 'TERM= <MAP=2> 
END 


The parser table specifies at label TERM: If the input command line 
matches a device specification ($DEV), then queue mapping number P2 to 
the IFORM queue, attach a character buffer to this queue element, and 
copy the device specification to the attached character buffer. The 
translator table specifies at label MRET: If P2 is in the IFORM 
queue, then output the contents of any attached buffer to the forming 
MCR command line. 


The following example illustrates the use of secondary mappings. 
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When translating the DCL MACRO command to the MCR MAC command, it is 
necessary to determine which (if any) input file specification has the 
qualifier /LIST on it. That is, the translator must be able to 
determine (by means of information in the TT) that the file 
specification "C" in the DCL command line "MACRO A,B,C/LIST,D" has the 
/LIST qualifier on it. The IFORM must map the DCL file specification 
that has the /LIST qualifier on it to the right position in the MCR 
command line. 


The mapping can more easily be understood from the viewpoint of the 
translator. The translator generates the MCR MAC command from left to 
right. When the translator reaches the position in the output MCR 
command line where the list file must be placed, the translator looks 
in the IFORM queue for the mapping number that represents the file 
specification with the /LIST qualifier on it. Since the file 
specification and qualifier are two distinct syntax elements, there 
are two mapping numbers in the IFORM queue to represent them. Also, 
Since the IFORM queue is a linear data stucture (and not a tree), a 
means of associating the /LIST qualifier with the file specification 
is needed. 


To express an association between elements in the IFORM queue, use 
primary and secondary mapping numbers. Secondary mapping numbers 
(such as S1) have meaning only as related to primary mapping numbers 
(such as Pl). 


The following MML notation expresses this mapping and illustrates’ the 
use of primary and secondary mappings. 


Parser Table 


AND "MACRO FILES 
END 
FILES: AND <SFILE MAP=1> <'/LIST OPT=T MAP=<,1>> <MORE OPT=T> 
END 
MORE: AND <<',>> FILES 
END 


Translator Table 


AND ‘MAC <OBJ OPT=T> <LST OPT=T> '= SELIF 
END 
LST: AND <<',>> <MAP=<1,1>> 
END 
SELIF: 


It is possible when parsing (due to the recursive definition of FILES) 
to queue to the IFORM queue identical map numbers ("P11") that 
represent the input file specifications. The only means of 
distinguishing the "Pl" map numbers is by their left-to-right 
positioning. For the translator to find the "P1" map number. that 
represents the file specification with the /LIST on it, the translator 
has to find the "Pl" map number that is followed by the "S1" map 
number such that there are no intervening "Pn" map numbers. In MML, 
to instruct the translator to perform such a search, use the argument 
"<MAP=<1,1>>", as specified at label LST. 


Remember that if a reference is made to a secondary map number without 
specifying a primary map number, then the translator looks for a 
secondary map number that is associated with the last used primary map 
number, 
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12.10.10 NO 


NO is allowed only in a PT. NO instructs the parser to process either 


a literal "NO" or a literal "-" before it processes the associated 
literal. The NO attribute is legal only when associated with a 
literal syntax element. The format for the NO attribute is as 
follows: 
NO=T 

If you specify a MAP with a NO, the parser queues two different 
mapping numbers. If the parser does not process either the "NO" or 
the "-", the parser queues the mapping number assigned to MAP. If the 
parser does process either the "NO" or the "-", the parser increments 


the mapping number by one before it queues the mapping number. 
The following illustrates the use of NO: 
OR <'LIST MAP=10. NO=T> 
In this example, the parser attempts to parse either NOLIST, -LIST, or 
LIST. If LIST is parsed, the parser adds the mapping number 10 to the 


IFORM queue. If either NOLIST or -LIST is parsed, the parser queues 
the mapping number 1l. 


12.10.11 OPT, OPTR 


Use OPT (OPTional) to indicate that a syntax element is not required. 
You can use OPT in both the PT andthe TT. The parser and the 
translator interpret OPT identically. The format for OPT is as 
follows: 


OPT=T 


For example, to specify that qualifiers (label QUAL) are optional 
syntax in the ASSIGN command, use the following MML notation: 


AND "ASSIGN <QUAL OPT=T> ... 
The parser goes to label QUAL and processes the syntax defined at 
label QUAL. If the parser cannot process a syntax element in an AND 
macro, the failure implies the failure of the AND macro. The OPT=T 


attribute tells the parser to ignore the failure and continue 
processing the AND macro with the next (left-to-right) argument to the 
AND macro. 


Use OPTR (OPTional Repeat) in the same way to indicate that a syntax 


element is not required. In addition, use OPTR to indicate that the 
syntax element can be used repeatedly in the parse/translation until a 
failure results. In other words, the presence of OPTR indicates that 


the syntax element can be used to parse or translate syntax from zero 
to an infinite number of times. The format for OPTR is as follows: 


OPTR=T 
For example, to specify that qualifiers (label QUAL) are optional 
syntax in the ASSIGN command and that the qualifiers can be used 
repeatedly in the input command line, use the following MML notation: 
AND ‘ASSIGN <QUAL OPTR=T> ... 
The parser goes to label QUAL and processes the syntax defined there. 


If a syntax element in an AND macro fails, the failure cannot be used 
in the parse, implies the failure of the AND macro. The OPTR=T 
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attribute tells the parser to ignore failure and to continue 
processing the AND macro with the next (left-to-right) argument to the 
AND macro. However, if and while the syntax defined at label QUAL 
matches the input command, the parser uses it repeatedly. 


If the OPT and AND attributes are used in the same syntax element, the 
OPT modifies the AND. That is, the OPT does not modify the entire 
syntax element. 


For example, here is a fragment of code based on the LINK command 
translator table. The TT specifies a TKB switch that can be specified 
with or without arguments attached. 


e 
° 


OR. <'/PR MAP=1 AND=PRIV OPT=T> 
END 

PRIV: AND 's <MAP=3> 
END 


In the example, the optional argument to the /PR switch is attached to 
mapping number 3. The OPT applies to AND=PRIV and not to the whole 
syntax element. If the OPT applied to the entire syntax element, then 
the entire OR macro, of which this fragment is a part, would always 
succeed. 


12.10.12 PRO 

Use PRO (PROmpt) in the PT to associate prompt strings with syntax 
elements. If the parser detects end-of-line while processing a syntax 
element. that has the PRO attribute specified, the parser prints’ the 
prompt string specified, and suspends itself to wait for more input. 
The parser appends any input received to the input DCL command line. 
PRO is legal only inthe PT. The translator does not prompt. The 
format of PRO is as follows: 


PRO='string 
or 
PRO=label 
label: PROMPT </string/> 
where: 
string ASCII string to be used as the prompt string 


label (MACRO-11) label of a (MACRO-11) PROMPT macro 


Thus, specify the prompt string directly after the symbol, or as 
the argument to the PROMPT macro. The PROMPT macro allows global 
prompt strings, which conserve space. 
The following example illustrates the use of PRO: 

AND <QUAL OPTR=T> <SDEV PRO='Device?> <SDEV PRO=PRODEV> 


PRODEV: PROMPT </Logical device? /> 
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The command requires two device specifications (S$DEV). If the parser 
expects the first S$DEV but reaches the end of the line, then the 
parser prompts as follows: 


Device? 


If the parser expects the second $DEV but reaches the end of the line, 
then the parser prompts as follows: 


Logical device? 


12.10.13 QUA 


Use QUA (QUAlifier) to specify qualifiers. You can specify floating 
or positional qualifiers. Floating qualifiers are qualifiers that are 
legal anywhere in the input DCL command line. Positional qualifiers 
are qualifiers that are legal only at specific positions in the input 
DCL command line or output MCR command line. 


The positional form of the QUA attribute is legal in both a PT and a 
TT. The floating form is legal only in a PT. The format for QUA is 
as follows: 


QUA=label 
where: 
label Nonliteral (address of an AND or OR macro) 


When the QUA attribute is used in a PT and the parser encounters a 
slash (/) in an appropriate location, it attempts to match the text 
following the slash with one of the elements of the AND or OR macro at 
the specified label. If an end-of-line is encountered after the 
slash, the parser issues a prompt. If an illegal qualifier is given, 
then an error message is printed and the parse is aborted. The list 
of qualifiers is repeatedly scanned until all qualifiers in the input 
command line have been parsed. 


To specify a positional QUA attribute, use QUA as part of a= syntax 
element. For example: 


AND <'ASSIGN,3 QUA=QUAL> SDEV S$DEV 
END 
QUAL: OR <'GLOBAL,1> 
OR. < 'LOCAL, 3> 
OR. <'LOGIN, 3> 
OR. TERM 
END 


In this case, any qualifiers (such as /GLOBAL) must immediately follow 
"ASSIGN" in the command line. (See the following example for more 
details on how the QUA attribute works.) 


To specify floating qualifiers, use QUA as a separate argument to an 
AND macro, not as part of another argument. The parser attempts to 
match the qualifiers defined at the label before and after it 
processes each argument of the AND macro. That is, the qualifiers 
float before and after each syntax element defined by the AND macro. 
Furthermore, the parser attempts to parse the floating qualifiers 


after any prompts. If QUA is being used to specify floating 
qualifiers, it must be an argument to an AND macro, rather than an 
AND. (extension) macro. The floating-qualifier form of QUA is legal 


only ina PT. 
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The following illustrates the floating-qualifier form of QUA: 


AND "ASSIGN, 3 S$DEV SDEV QUA=QUAL 
END 

QUAL: OR <* LOCAL, 3> 
OR. <'LOGIN,3> 
OR. < ‘GLOBAL, 1> 
OR. TERM 
END 

The label QUAL defines the allowable qualifiers. The parser checks 


for the qualifiers before, between, and after the SDEV_. syntax 
elements. Before the parser transfers parsing control to the OR macro 
at label QUAL, the parser attempts to parse the slash "/" character. 
Only if the parser successfully parses the slash, does it attempt to 
parse the qualifiers defined at label QUAL. If the parser detects the 
end of the input DCL command line after it parses a slash character, 
the parser prompts for more input. If a slash is detected and the 
qualifiers defined at label QUAL fail to process, the parser issues an 
error message and aborts the parse. The parser repeatedly attempts to 
parse the qualifiers until it no longer can parse a slash character. 


Thus, using QUA in the previous example is equivalent to the 
following: 


AND <QUAL OPTR=T> S$DEV <QUAL OPTR=T> $DEV <QUAL OPTR=T> 
END 
QUAL: AND '/ <QUAL1 PRO='Qualifier? ERR=<'Illegal qualifier>> 
QUAL1: OR <'LOCAL, 2> 
OR. <'LOGIN, 2> 
OR. <'GLOBAL, 1> 
END 


The following illustrates the use of the QUA attribute ina TT. 


ASN: : AND <<'ASN >> <MAP=1> ‘= <MAP=2 QUA=LAUQ> 
END 
LAUQ: OR <'GBL MAP=4> 
OR. <'LOGIN MAP=3> 
OR. MRET 
END 


The label LAUQ defines the MCR switches equivalent to the DCL 
qualifiers. The translator processes QUA just as does the parser. 
However, instead of parsing the input DCL command line for qualifiers, 
the translator uses the qualifiers to construct the equivalent MCR 
command line. Remember that QUA automatically includes slashes before 
each switch. 


12.10.14 TST 

TST is legal only in a TT and only when specified with MAP. TST 
instructs the translator not to mark a mapping element used in a 
translation as having been used. The format of the TST attribute is 
as follows: 


ST=T 
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The following illustrates the use of the TST attribute: 


MCRCOP: OR <PIP MAP=1 TST=T> 
OR. <PIP MAP=2 TST=T> 
OR. <NFT MAP=3 > 
END 


In the previous example, the OR macros instruct the translator to 
process the nonliteral PIP if either mapping numbers 1 or 2 are in the 
IFORM queue, or to process the nonliteral NFT if mapping number 3 is 
in the IFORM queue. The TST attribute associated with the syntax 
element PIP instructs the translator not to mark mapping numbers 2 or 
3 as having been used. This allows the syntax defined at label PIP to 
use these mapping numbers also. 


12.11 PREDEFINED SYNTAX ELEMENTS 


Predefined syntax elements (PSEs) are syntax elements defined for use 
by all DCL command tables. PSE names, by convention, are 
distinguished from local category names by having a "$" as their first 
character. 


NOTE 


If the syntax of a command does not match that of a 
predefined syntax element, then the parse fails. 
Several PSEs have two forms, one ending with an "E" 
and one not, such as $NOD and $NODE, $FIL and SFILE, 
SDEV and $DEVE, and $UIC and SUICE. The form ending 
in "E" produces an error message before aborting the 
parse. The shorter form does not. Use the shorter 
form when defining optional syntax. 


The following list briefly defines the PSEs. Note that some PSEs 
require arguments. Specify the required arguments in the order shown 
and enclose the PSE and the arguments in angle brackets to identify 
the PSE and arguments as one argument to the MACRO-11 assembler. 


12.11.1 Basic Data Types 


The following list of PSEs define basic data types in MML. You can 
use them only ina PT. The parser copies to an IFORM character buffer 
the text in the input DCL command line that fits the structure defined 
by the PSE. The buffer is attached to the last queued mapping number 
and can be accessed by the translator for use in constructing the 
equivalent MCR command line. 


$NUM,A1,A2 Defines the structure or syntax of a numeric. string 
(O through 9). The arguments Al and A2 designate the 
minimum and maximum length, respectively, for the 
numeric string. Additionally, the PSE allows an 
optional decimal point on the end of the string. The 
decimal point is not copied to the IFORM character 
buffer. 
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$DNUM,A1,A2 


SONUM,A1,A2 


SWONUM,Al1,A2 


SDONUM,A1,A2[.] 


SWDONUM, Al ,A2 


$BNUM,A1,A2 


SALF,A1,A2 


SALFN,A1,A2 


SWALFN,A1,A2 


$R50,A1,A2 
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Defines the structure or syntax of a decimal numeric 
string (0 through 9). The arguments Al and A2 
designate the minimum and maximum length, 
respectively, for the numeric string. Additionally, 
the PSE allows an optional decimal point on the end 
of the string. A decimal point is copied to the 
IFORM character buffer whether or not it is specified 
in the input DCL command line. 


Defines the structure or syntax of an octal numeric 
string (0 through 7). The arguments Al and A2 
designate the minimum and maximum length, 
respectively, for the numeric string. 


Defines the structure or syntax of S$ONUM or the 
wildcard character "*". The arguments Al and A2 
designate the minimum and maximum length, 
respectively, for the numeric string. 


Defines the structure or syntax of a decimal or octal 
numeric string (0 through 9). The arguments Al and 
A2 designate the minimum and maximum length, 
respectively, for the numeric string. Additionally, 
the PSE allows an optional decimal point on the end 
of the string. A decimal point is copied to the 
IFORM character buffer if either the input DCL 
command line or the parsed string contains’ the 
characters 8 or 9. 


Defines the structure or syntax of $DONUM or a "*" 
character. The arguments Al and A2 designate the 
minimum and maximum length, respectively, for the 
numeric string. 


Defines the structure or syntax of a binary numeric 
string (0 through 1). The arguments Al and A2 
designate the minimum and maximum length, 
respectively, for the numeric string. 


Defines the structure or syntax of an alphabetic 
string (A through 2Z). The arguments Al and A2 
designate the minimum and maximum length for the 
alphabetic string. 


Defines the structure or syntax of an alphanumeric 
string (0 through 9 and/or A through 2). The 
arguments Al and A2 designate the minimum and maximum 
length for the alphanumeric string. 


Defines the structure or syntax of SALFN with the 


additional characters: kas and oe id These 
characters are used by some RSX-11M/M-PLUS utilities 
as wildcard characters. The arguments Al and A2 


designate the minimum and maximum length for the 
alphanumeric string. 


Defines the structure or syntax of a Radix-50 string 
(O through 9, A through Z, "S$", and "."). The 
arguments Al and A2 designate the minimum and maximum 
length for the Radix-50 string. 
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12.11.2 Common Command Elements 


The following PSEs define parts of the DCL command grammar. You can 


use them 


only ina PT. The text (except for $DATE) parsed from the 


input DCL command line that fits the structure defined by the PSE is 


copied to 


IFORM character buffer that is attached to the last 


queued mapping number. 


SFIL 


SFILE 


SWFIL 


SWFILE 


SNFIL 


SNFILE 


SIFIL 


SIFILE 


SNOD 


SNODE 


$ DEV 


$ DEVE 


Defines the structure or syntax of a file 
specification. Each element explicitly included in the 
file specification sets a bit in the global bit-mask 
words. These are: 


device B28 filetype B31 
UIC B29 version B32 
filename B30 


These bits are also set by the other S$FIL-based 
predefined syntax elements. 


Defines the structure or syntax of $FIL. Additionally, 
if the parser fails to process S$FILE, the parser issues 
an error message and aborts the parse. 


Defines the structure or syntax of $FIL. Additionally, 
the wildcard characters: "*" and "%$" are allowed as 
part of the file specification. 


Defines the structure or syntax of SWFIL. 
Additionally, if tr2 parser fails to process SWFILE, 
the parser issues an error message and aborts’ the 
parse. 


Defines the structure or syntax of S$WFIL if preceded by 
a DECnet node specification. 


Defines the structure or syntax of SNFIL. 
Additionally, if the parser fails to process S$NFILE, 
the parser issues an error message and aborts’ the 
parse. 


Defines the structure or syntax of $FIL. Additionally, 
the indirect file indicator "@" must prefix the file 
specification. 


Defines the structure or syntax of SIFIL. 
Additionally, if the parser fails to process S$IFILE, 
the parser issues an error message and aborts’ the 
parse. 


Defines the structure or syntax of a DECnet node name 
specification. 


Defines the structure or syntax of $NOD. Additionally, 
if the parser fails to process $NODE, the parser issues 
an error message and aborts the parse. 


Defines the structure or syntax of a device 
specification. 


Defines the structure or syntax of S$DEV. Additionally, 


if the parser fails to process SDEVE, the parser issues 
an error message and aborts the parse. 
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Defines the structure or syntax of $DEV. Additionally, 


the character ":" is optional syntax. 


Defines the structure or syntax of SODEV. 
Additionally, if the parser fails to process SODEVE, 
the parser issues an error message and aborts’ the 
parse. 


Defines the structure or syntax of a UFD specification. 


Defines the structure or syntax of $UIC. Additionally, 
if the parser fails to process $UICE, the parser issues 
an error message and aborts the parse. 


Defines the structure or syntax of $UIC. Additionally, 
the wildcard character "*" is allowed as part of the 
UIC specification. 


Defines the structure or syntax of SWUIC. 
Additionally, if the parser fails to process $WUICE, 
the parser issues an error message and aborts’ the 
parse. 


Defines the structure or syntax of $UIC. Additionally, 
the characters "[", "J", and "," are optional syntax. 


Defines the structure or syntax of SOUIC. 
Additionally, if the parser fails to process SOUICE, 
the parser issues an error message and aborts’ the 
parse. 


Defines the structure or syntax of a date 
specification. A date specification can take one of 
two forms: mm/dd/yy or dd-mmm-yy. $DATE produces’ the 
following data structures in the IFORM queue: the day 
is attached to secondary mapping number 210, the month 
is attached to secondary mapping number 211, and the 
year is attached to secondary mapping number 212. The 
output format is always dd-mmm-yy (with the first three 
characters of the month name spelled out) even if the 
slash format (with the number of the month) is used. 


For commands that require two dates (for example, SINCE 
and THROUGH), a second PSE for dates, $DATE1, uses 
secondary mapping numbers 213, 214, and 215 for the 
day, month, and year respectively. $DATE1l is otherwise 
identical to $DATE. 


Defines the structure or syntax of a time 
specification. The time specification is of the form 
hh:mm[:ss]. 


12.11.3 Special Parser Elements 


You can specify the following PSEs only in a PT. 


SALL, label 


Defines the syntax or structure of an arbitrary string 
of characters. SALL matches all characters in the 
command line (left-to-right) until any one of a set of 
specified terminating characters is detected. The set 
of terminating characters are specified with the 
TERMINATORS macro. The label is a label on the 
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TERMINATORS macro. The text parsed from the input DCL 
command line that fits the structure defined by S$ALL is 
copied to an IFORM character buffer that is attached to 
the last queued mapping number. 


Here is an example of SALL with the TERMINATORS macro: 


AND. <SALL,EXCEPT> 


EXCEPT: TERMINATORS '" ') '] SEOL 
This example allows the "," the ")", and the "J" as 
terminators, in addition to the SEOL predefined syntax 


element, discussed next. 


SEOL SEOL is used to parse end-of-line characters. For 
instance, in the previous example, a carriage-return or 
escape would also be acceptable as a terminator. 


SCOP, ‘lit $COP does not define syntax. S$COP instructs the parser 
to copy the specified literal, ‘lit, unconditionally to 
an IFORM character buffer. The IFORM character buffer 
is always attached to the last queued mapping number. 


$DSB $DSB (disable skip blanks) does not define syntax. 
SDSB instructs the parser not to skip. blanks. 
Normally, blanks are ignored. $DSB and SESB must be in 
the same syntax element, such as AND or OR, but need 
not be on the same line. 


SESB SESB (enable skip blanks) does not define syntax. SESB 
restores the default state, which is to ignore blanks. 


For example, a file specification cannot include 
blanks. The following could define a file 
specification: 


S$DSB $DEV $UIC <$ALFN,0,9> '. <S$ALFN,0,3> '; <SONUM,0,3> S$ESB 


(The actual file specification definition is more 
complex. This is only an example.) 


SDDR S$DDR does not define syntax. S$DDR instructs the parser 
to disable delimiter recognition. Delimiter 
recognition is enabled by default and instructs the 
parser to ensure that all literal syntax elements have 
delimiting characters terminating them. $DDR must be 
used on the same line with $EDR. See the next example. 


SEDR Enable delimiter recognition. This is the default 
case. 


For example, the following line allows you to attach 


the first one to three characters to one mapping number 
while the remainder are attached to another. 
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COM1: AND S$DDR <$R50,1,3 MAP=1> <$R50,0,7 MAP=2> SEDR 
END 


Notice that no delimiting character distinguishes the 
two strings, and that the second string may be null. 


$SEP defines the colon (:) or equals (=). These are 
used as separators between qualifiers and arguments. 


SOSEP defines an optional separator, that is colon, 
equals, or null. 


$CSEP is the same as $SEP, but additionally copies a 
colon to the IFORM. 


S$COSEP is the same as SOSEP, but additionally copies a 
colon to the IFORM whether anything is input or not. 


$FSEP defines the comma (,) and plus (+) as _ file 
specification separators. 


STERM defines a terminal specification and copies it to 
the IFORM. 


S$PROC defines. a processor name for the Queue Manager as 
either a device name followed by a colon or six 
Radix-50 characters followed by a colon. 


SPRONC defines a processor name for the Queue Manager 
as a device name followed by a colon or six Radix-50 
characters not followed by a colon. 


12.11.4 Special Translator Elements 


You can specify the following PSEs only in a TT. 


SNEW 


SRESET 


SFNAM 


SSY 


STI 


Used to indicate the start of an additional MCR command 
line. SNEW instructs the dispatcher subprocess of the 
DCL task that there are multiple MCR commands that must 
be dispatched serially. 


Used to reset the IFORM queue. Resetting the IFORM 
queue allows all used mapping numbers to be reused. 
SRESET is designed to be used with S$NEW to define 
multiple MCR commands. 


Used to specify that only the file name in ae file 
specification is to be copied to the MCR command line 
buffer as a result of unmapping a mapped file 
specification. 


Converts the assigned device for SY: to ASCII and 
appends it to the MCR command line; for example, DB2:. 


Converts the assigned terminal device for TI: to ASCII 


and appends it to the MCR command line; for example, 
TT LS. « 
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Converts the current UIC for the user to ASCII and 
appends it to the MCR command line; for example, 
[301,113]. 


Converts the login UIC for the user to ASCII and 
appends it to the MCR command line. 


12.11.5 Program Control Elements 


You can specify the following PSEs in either a PT or a TT. 


SJSR,A 


S$TST 


STSTNOT 


SLOAD, name 


SCALLOV, name 


SNULL 


SAB 


SBA 


A special category used to gain control of the CPU. 
The argument A must be the label of a MACRO-11 
subroutine. To indicate failure, the MACRO-11 
subroutine should (on return) set the carry bit to 
indicate failure and clear it to indicate success. 
Remember, the routine must be in the blank program 
section. 


STST is used to test if a mapping number is in the 
IFORM queue. A MAP attribute specifies the mapping 
number. $TST succeeds only if the mapping number is in 
the IFORM queue; for example, <S$TST MAP=1>. 


STSTNOT is used to test if a mapping number is not in 
the IFORM queue. A MAP attribute specifies the mapping 
number. $TSTNOT succeeds only if the mapping number is 
not in the IFORM queue. The syntax is identical to 
STST. 


SLOAD is used to load an overlay from a parser or 
translator table. The argument "name" specifies the 
name of the overlay as specified in the overlay 
description file. 


SCALLOV is used to load and activate part of either a 
parser or translator table. The starting address 
within the overlay must be contained in the first word 
of the overlay. Use .WORD to specify the address. On 
return, the previous overlay is loaded. The argument 
"name" specifies the name of the overlay as specified 
in the overlay description file. 


SNULL is used to execute attributes without specifying 
a syntax element. SNULL succeeds if the attributes 
succeed. 


SAB (angle bracket) is equivalent to the literal "<" 
and is used to pass the "<" as an argument to MACRO-11l. 


SBA is equivalent to the literal ">" and is used to 
pass the ">" as an argument to MACRO-11. 
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CHAPTER 13 


POOL MONITORING SUPPORT 


Pool monitoring support controls the use of the system's dynamic 
storage region (pool). This support monitors pool levels, restricts 
use, and notifies you when pool is near depletion. This support 
consists of two parts: the RSX-11M/M-PLUS Executive pool monitor 
code, and the privileged Pool Monitor Task (PMT). 


Pool monitoring support is not available on unmapped systems. 


13.1 HOW YOU GET POOL MONITORING SUPPORT 


On RSX~11M systems, you receive pool monitoring support when you 
select the pool monitoring support option in system generation 
(SYSGEN). If you select the option, you receive the Executive pool 
monitor code and SYSGEN assembles and task-builds PMT. If you do not 
select the option, you do not receive any pool monitoring support. 


ering support, including the 
s included by default. SYSGEN 
1eed not select any option for 


On RSX-11M-PLUS systems, poo 
Executive pool monitor code 
establishes the support for you 


One of PMT's features is that it responds to extreme fragmentation. 
Due to the seriousness of this pool problem, PMT requires your 
interaction to aid in system recovery. Therefore, if you select pool 
monitoring support, you must be prepared to respond to PMT's prompts 
(see Section 13.3.4). 


13.2 THE EXECUTIVE POOL MONITOR CODE 


The pool monitor code within the Executive monitors the amount of free 
pool and detects major pool events. When a major pool event occurs, 
the Executive notifies PMT of the event and of the current condition 
of pool. 


13.2.1 Pool Events Affecting the Executive 


The Executive pool monitor code responds to three major pool events. 
One is classified as a high pool event and two are classified as low 
pool events. The occurrence of these events directly affects the 
condition of pool, creating either a high or low pool condition. The 
Executive responds by notifying PMT of the pool event and the 
resultant pool condition and also activates PMT. Any further response 
to the pool condition is left to PMT. 
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13.2.1.1 High Pool Event - The following is the possible high pool 
event: 


e The attainment of a high pool condition from a low pool 
condition. 


This event occurs when a system that has a low pool condition 
relinquishes enough pool to cause the amount of free pool to rise 
above the high limit. 


The high pool limit is set using the MCR and VMR SET /PLCTL command. 
See Section 13.4 for further discussion of the high limit. 


13.2.1.2 Low Pool Event - The following are the possible low pool 
events: 


e The degradation of pool from a high pool condition to aéé low 
pool condition 


@ A pool allocation failure 


The degradation of pool occurs when the total amount of free pool has 
fallen below the low limit. A pool allocation failure occurs when the 
largest pool fragment is too small for the process requesting it. A 
pool allocation failure is not to be confused with future discussions 
in this chapter of pool fragmentation. Pool allocation failures and 
pool fragmentation are, in the context of this chapter, different pool 
problems and are, therefore, discussed separately. See Section 13.3.1 
for additional information on pool fragmentation. 


The low pool limit is set using the MCR and VMR_ SET /PLCTL command. 
See Section 13.4 for further discussion of the low limit. 


13.2.1.3 Pool Monitoring Interface - The mechanism used by the 
Executive to detect pool events is called the pool monitor interface. 
The details of how this interface works are beyond the scope of this 
manual. However, it is fully described in the source code for the 
Executive module CORAL.MAC. CORAL.MAC is in [11,10] on your kit. In 
summary, the interface functions as follows: 


@e Provides the Executive with the ability to declare information 
to a pool monitor task. 


e Provides the Executive with the capability to receive a 
response or acknowledgement from a pool monitor task. (An 
acknowledgement can be used by the Executive to control 
further information declarations.) 


13.2.2 Pool Conditions 


The condition of pool is directly related to major pool events’) and 
also to the acceptable high and low pool limits you specify. (You set 
and manipulate these limits using either the MCR or VMR_ SET /PLCTL 


command described in Section 13.4). When a major pool event occurs 
and causes the size of free pool to cross the low or high limit, a new 
pool condition exists. The possible pool conditions are low pool and 
high pool. 
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A high pool condition exists when the amount of free pool is 
sufficient to support current and less demanding system workloads. 


A low pool condition exists when the amount of free pool is nearing 
the point where system performance will degrade seriously if the 
system's workload increases. 


Major pool events cause either a high or low pool condition to exist. 
In turn, a high or low pool condition, combined with a specific pool 
fragmentation level, creates either a high or low pool. state. Pool 
states are discussed in Section 13.3. 


13.3 THE POOL MONITOR TASK 


The Pool Monitor Task (PMT) is task built and installed during the 
SYSGEN procedure. Whenever the resultant system is bootstrapped, PMT 
is activated by the Executive. . 


(If you do not wish to use the DIGITAL-supplied Pool Monitor Task, you 
do have the option to write and run your own pool monitor task. If 
you wish to write your own pool monitor task, you should first be 
familiar with the Executive pool monitor interface. The interface is 
documented in the Executive module [11,10]CORAL.MAC. A task, with the 
task name "PMT...", installed on a system that supports pool 
monitoring, is considered to be a “pool monitor task".) 


PMT's first responsibility is to monitor pool conditions. The 
conditions that PMT responds to include those detected and reported by 
the Executive (see Section 13.2). PMT's second responsibility is to 
monitor pool fragmentation. Through this monitoring, PMT can respond 
to another major pool event and also react to extreme pool 
fragmentation. The other major pool event (not reported by the 
Executive) occurs when PMT detects that the largest free pool fragment 
is less than the minimum required fragment size. (See Section 13.3.4 
for further discussion of extreme fragmentation.) 


Once it has been activated by the Executive, PMT basically operates in 


a cycle. PMT determines the size of the largest pool fragment 
whenever it receives the Executive's notification of a pool condition, 
or at least at regular time intervals. It then compares this size to 


the minimum required fragment size. Based on the Executive's report 
on the current pool condition and what PMT detects when monitoring 
fragmentation, PMT determines what the current state of pool is and 
responds to it accordingly. 


The minimum required fragment size is set using the MCR and VMR_ SET 
/PLCTL command. See Section 13.4 for further discussion of the 
minimum required fragment size. 


13.3.1 Conditions Affecting PMT 


PMT responds to pool fragmentation and to pool conditions; however, 
the response varies depending upon the current level of pool 
fragmentation. The two levels that influence PMT's response are as 
follows: 


1. If the largest fragment is equal to or greater than the 


minimum required fragment size, PMT then acts only on the 
condition of pool as reported by the Executive. 
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2. If the largest fragment becomes smaller than the minimum 
required fragment size, PMT considers this to be a low pool 
event. If the system is not already in a low pool. state, 
this event causes a transition to that state. PMT then 
responds accordingly. 


Although extreme fragmentation is another pool event that PMT responds 
to, it is different from those previously described. It is defined 
and documented in Section 13.3.4. 


PMT uses the information it has concerning the current level of 
fragmentation and also the information provided by the Executive to 
determine the overall state of pool. Following is a discussion of 
PMT's response to specific pool events and conditions. 


13.3.1.1 Pool Level and Fragment Size Are Satisfactory - The 
Executive notifies PMT that the pool level is above the high limit and 
PMT detects that fragment size is greater than the minimum required 
fragment size. 


PMT concludes that a high pool state exists and executes actions 
appropriate for a high pool state (see Section 13.3.2). 


13.3.1.2 Low Pool Condition - The Executive notifies PMT that a low 
pool condition is achieved. 


PMT determines whether the change in pool reported by the Executive is 
temporary. The change is temporary if, by the time PMT responds to 
the Executive's notification, enough free pool has accumulated to push 
the total above the high limit. If the change is temporary, PMT 
ignores the notification and continues to execute high pool state 
actions. If the change is not temporary, PMT concludes that a low 
pool state exists and executes actions appropriate for a low pool 
state (see Section 13.3.3). 


13.3.1.3 High Pool Condition - The Executive notifies PMT that a high 
pool condition is achieved. 


PMT determines whether the change in pool reported by the Executive is 
temporary. The change is temporary if, by the time PMT responds to 
the Executive's notification, the total amount of free pool has moved 
below the high limit. If the change is temporary, PMT ignores the 
notification and continues to execute low pool state actions. If the 
change is not temporary, PMT initiates actions appropriate for a high 
pool state (see Section 13.3.2). 


13.3.1.4 Largest Pool Fragment Is Too Small - PMT detects that the 
largest pool fragment is smaller than the minimum required fragment 
size. 


PMT concludes that a low pool state exists and executes actions for a 
low pool. state. Note that this low pool state overrides any pool 
conditions reported by the Executive. This pool event will cause the 
system to be in a low pool state even if the Executive reports a high 
pool condition. 
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13.3.1.5 Largest Pool Fragment Becomes Larger - PMT detects that the 
size of the largest pool fragment has become larger than the minimum 
required fragment size. 


PMT decides that the current pool state must be based on the latest 
pool condition reported by the Executive. If the Executive reported a 
high pool condition, PMT decides that a high pool state exists. If 
the Executive reported a low pool condition, PMT decides that a low 
pool state exists. In either situation, PMT takes the appropriate 
action for that state. 


13.3.2 PMT Default Actions for a High Pool State 


When PMT concludes that a high pool state exists, it executes the 
following actions: 


1. Sets its internal cycle interval to 1 minute 
2. Enables checkpointing for itself 
3. Removes any pool use controls 
PMT then stops itself so that its impact on system resources is 


minimized. PMT unstops itself when the internal cycle interval has 
elapsed. 


13.3.3 PMT Default Actions for a Low Pool State 


When PMT concludes that a low -pool state exists, it executes’ the 
following actions: 


1. Disables checkpointing for itself. 
2. Sets its internal cycle interval to 20 seconds. 
3. Establishes pool use controls as follows: 

a. Prevents nonprivileged users from logging in. 


b. Suppresses INSTALL/RUN/REMOVE sequences on nonprivileged 
terminals. ; 


c. Delays nonprivileged task loading. 
NOTE 


Nonprivileged tasks with a task priority less 
than the specified base priority cannot compete 
for memory resources until a high pool. state 
exists (see Section 13.4.3). This does not mean 
that such tasks cannot be requested; they will 
simply remain blocked from execution until PMT 
concludes that a high pool state exists. All 
other tasks, including any tasks already active 
at the onset of the low pool state, are not 
affected by this control. 
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d. Sends a warning message to all logged-in terminals (or 
on-line terminals on systems without multiuser 
protection). This message cannot be suppressed by the 
MCR SET /NOBRO command or the DCL SET TERM /NOBROADCAST 
command. 


e. Sends a warning message to and displays pool statistics 
at the console terminal. 


13.3.3.1 PMT Output to Terminals During Low Pool State - When PMT 
determines that a low pool state exists, PMT sends the following 
warning message to logged-in terminals (or on-line terminals on 
systems without multiuser protection): 


OB-AUG-85 13235210 -- Low rool -- Flease exit active tasks - 7FFHYR 


The effectiveness of this message depends on whether users exit from 
their active tasks. If they choose to ignore this message, a low pool 
state continues to exist. 


ZEPHYR is the system name selected during SYSGEN or the DECnet node 
name (if DECnet is running on your system). 


PMT sends this message at 20-second intervals until it concludes’ that 
a high pool state exists. 


13.3.3.2 PMT Output to the Console Terminal During Low Pool State - 
In a low pool state, PMT also sends a warning message to and displays 
pool statistics at the console terminal. The following is an 
annotated example of PMT output to the console terminal: 


O8-AUG-85 13235310 -- Warning -~= Pool is critically low @ 
Total free rool = 1116. bytes 
Largest fragment = 112. bytes & 


In this example, PMT: 
@ Sends a warning message 


@ Displays the amount of free pool existing at the onset of 
the low pool state 


© Displays the size of the largest free fragment of pool 
existing at the onset of the low pool state 


PMT broadcasts this message at 20-second time intervals until it 
concludes that a high pool state exists. 


13.3.4 PMT Default Actions for Extreme Fragmentation 


Extreme fragmentation exists when the largest pool fragment is less 
than 84(decimal) bytes. In this case, pool is exhausted and it is not 
pessible to free any pool by unsolicited terminal input, for example, 
issuing an ABORT command. At this point, PMT takes immediate action 
to prevent total pool depletion by executing the following steps: 


1. Enters kernel mode, which prevents any other tasks from 
executing but does allow the system to respond to device 
interrupts. 
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2. Prevents the invocation of TKTN. (Invoking TKTN at this time 
depletes the available pool.) It does this by clearing TKTN's 
special TCB pointer that is stored within the Executive. 


3. Sends a warning message to the console terminal. 


4. Prompts you to abort one or more of the tasks displayed. 
(You must’ be at the console to free pool in response to the 
PMT prompts.) After you select a task to abort, PMT returns 
to user mode until the abort operation is finished. 


5. Displays a message at the terminal running the task and the 
console terminal if the task is successfully aborted. 


6. Displays (upon request) an updated list of abortable tasks at 
the console terminal. 


(On RSX-11M systems 84(decimal) bytes is the size of a CLI command 
buffer.) 


13.3.4.1 Abortable Tasks - The abortable task list includes only 
those tasks that PMT considers eligible to abort. A task is abortable 
if it meets the following requirements: 


e It must be active. 

@e It must be resident in memory. 

@e It cannot be privileged and running from the console terminal. 
e It cannot be a Command Line Interpreter (CLI) task. 

@ It cannot be an Ancillary Control Processor (ACP) task. 

e It cannot be the task loader. 


e It cannot have any internal conditions that prevent it from 
exiting upon an abort request (for example, it is already 
aborted). 


The ability to abort tasks included in this list is a powerful feature 
and one that is potentially harmful to your system. You should abort 
tasks that consume pool and are relatively expendable. This action 
should release pool resources for use by the remaining active tasks 
and allow the system to continue operation, rather than deadlock over 
pool resources. 


It is important that you use discretion when selecting tasks to abort. 
Aborting certain tasks could render all or part of the application 
unusable. You can abort certain tasks (for example, PIP or MAC) and 
experience relatively few side effects. As an added measure of 
protection for your system, PMT does not, by default, include in the 
abortable task list the privileged tasks running from the console 
terminal. Therefore, if it is possible, you should run the privileged 
tasks that you do not want considered abortable (by PMT) from the 
console terminal. 
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13.3.4.2 PMT Messages - When extreme pool fragmentation occurs, PMT 
displays a message in the following format and a list of abortable 
tasks at the console terminal: 


dd-mmm-yy hh:mm:ss -- Warning -- Free pool exhausted 
Abortable tasks in memory: 


tttttt P I /O=xxx. ttnn: 
where: 
tttttt The name of the abortable task 


P The indicator that the task is privileged (a blank means 
that it is nonprivileged) 


XXX The total outstanding I/O count for the task 
ttnn The terminal where the task is running from 


PMT lists the tasks in order of decreasing priority but does not 
display the priority of individual tasks. 


PMT then prompts you to select one of the tasks from the list as 
follows: 


Enter o# task to unort: or press RFTURN to exit? 


If the task you specify is not installed or not on the list of 
abortable tasks, PMT displays one of the following messages: 


~v 1 


Tesk mob anetseblled:s tres adaint 


wr ke ier ® i : a Oe: Meee | ab 45 ig mill ead ag a 
esko ook eforkheds his asedqini 


PMT displays the list of abortable tasks if you press LINE FEED in 
response to either prompt. If you press RETURN, PMT relinquishes 
control of the system, by returning to user mode, for at least seven 
seconds, giving the system an opportunity to recover from the low pool 
state unassisted. 


If PMT is not able to abort the task you specify and the task is 
listed as abortable, PMT displays the following message (this occurs 
only if the task exits before PMT is able to abort it): 


Taek mot ehartertes bre attain 


If PMT successfully aborts the task, it sends the following message to 
the console terminal: 


*ECEETE bored 
Also, if the task was not running from the console terminal, PMT 
displays the following messages at the terminal where the task is 
running from: 
G9—9SUG-AS PELEIt10 -- Warnings -- Free faol] exhausted 
"LELtti" sborted 
PMT then sends the following message to the console terminal: 


Preag LINE FEED for an updated task list: 
enter 6 task to shorts or eress RETURN to exit? 
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13.3.4.3 Annotated Example of PMT Output for Extreme Fragmentation - 
An annotated example of PMT output for extreme fragmentation is shown 
in the following example. The numbers in the example correspond to 
the numbered items in the list that follows Example 13-1. 


Example 13-1 PMT Output for Extreme Fragmentation 
B:AUG3BS 13242123 <--> Warnings xo: Eree eool exhausted 1) 
Abartsable tasks io mewors? @Q 
EMNEMO E Iffle QO. EEO: 


af.03o E' T/Oz ts TESaOs 


ENITIA T/H= tla TT142 
MALT 29 [éQz td. TT202 
TEST LZO= Oa Caos 

ELET241 IgO= 1. Ligiz 
MACT 47 1/O= il. TI4Zi 


Enter a task to aborts or eresa BEIUEN to exiti PIPT21 © 
"BIET2i" aborted QO 


Bress LINE EEEU for an usedated task Listes 
@utler ge bLask to e@borts or &ress BETUBN ta exaiti 5] 


Hbhurteble tasks in memorys 6] 


RMOEMO Ep IfO=e O.4 TOs 
COT ae F I/O O42 ITOs 


At.7Tao E I7Oez ids TTSas 
EhnII14 Pe hea: TTi4i 
MALT2O Tf La Eros 
TEST I/O= oO. COo3. 

MACTAZ TOs iL: TI4zi 


Ember @ task to sborte or eress RETURN to exits EDT @ 

Task mol aingstalleds tres assini EDIT14 © 
fENITI4" sborted © 

feess LINE FEED for an ugdated task liste 

eoter @ task to aborts or eress RETURN to EXIT: (er ® 

In this example, PMT: 

0 Sends a warning message to logged-in terminals (or on-line 

terminals if the system does not support multiuser 


protection). 


Displays ‘the list of abortable tasks at the console 
terminal. 


Prompts for a task to abort (PIPT21 is entered). 


Aborts "PIPT21". 


ooo 9 


Prompts for an updated task list, a task to abort, or an 
exit. (A LINE FEED is entered for an updated task list.) 
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Displays the list of abortable tasks. 
Prompts for a task to abort (EDT is entered). 


Indicates that a task with the name "EDT" is not installed, 
and requests that you try again (EDIT14 is entered). 


Aborts "EDIT14". 


80 0690 9 


Prompts for an updated task list, a task to abort, or an 
exit. (The RETURN key is pressed for an exit.) 


13.3.5 PMT Task-Build Options 


You can modify PMT's response to pool conditions by editing PMT's 
task-build file PMTBLD.CMD and task building PMT again. If you wish 
to modify PMT, you must do the following: 


1. Remove PMT (the task name is PMT...) by using VMR 
2. Edit the task-build file 

3. Task build PMT again 

4. Install the modified task image by using VMR 


When the system is rebooted, the new PMT task will begin executing. 
If, however, you want the modified task image to run immediately, you 
must first abort PMT before you remove and reinstall it using MCR or 
DCL. 


You can modify the following PMT features: 
e® Timing control 
e Actions 
@ Pool use controls 


The specifics of modifying PMTBLD.CMD are documented in the file 
itself. Following is a discussion of the PMT features that you can 
modify. 


13.3.5.1 Controlling PMT Timing - PMT basically operates ina cycle. 
It becomes unstopped at regular intervals to monitor fragmentation and 
then stops itself. When the Executive interrupts the cycle to report 
a new pool event, PMT resets the cycle to begin at the point at which 
it was interrupted. 


PMT's cycle can have one of two possible time lengths. The length 
depends on the current state of pool. If a low pool state exists, the 
cycle is 20 seconds long (plus the time PMT requires to execute all 
low pool state actions). If a high pool state exists, the cycle is 60 
seconds long (plus the time PMT requires to execute all high pool 
state actions). 


You can modify PMT's cycle; however, the only modification allowed is 
lengthening the high pool state cycle. The 60-second value is not 
only the default value but also the minimum value that you can 
specify. If you lengthen the cycle, PMT may not be as effective at 
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monitoring pool fragmentation problems. You can partially compensate 
for this, by using the SET /PLCTL command (see Section 13.4.2) to 
increase the minimum size of the largest pool fragment parameter. 
This ensures that PMT will detect imminent pool fragmentation problems 
earlier. 


13.3.5.2 Controlling PMT Action - You can modify some of the actions 
that PMT executes during the cycle. The actions are as follows: 


@e Sending warning messages to logged-in terminals (or on-line 
terminals on systems that do not support multiuser protection) 


e Forcibly checkpointing stopped tasks in memory 
@ Aborting certain privileged tasks 


When a low pool state exists, PMT sends warning messages to logged-in 
terminals (or on-line terminals on systems that do not support 
multiuser protection). You can suppress this action by modifying 
PMTBLD.CMD and task building PMT again. 


When a low pool state exists, PMT requests the Executive to forcibly 
checkpoint all memory-resident stopped tasks without outstanding 
nonbuffered I/O. These tasks include CLI tasks, ACP tasks, and tasks 
with outstanding buffered I/0, only if they are stopped during a low 
pool state. When the Executive checkpoints a task, it deallocates the 
task header, thereby reducing fragmentation. 


You can modify PMTBLD.CMD to enable such checkpointing for a high pool 


state as well. This reduces the effect of long-term fragmentation, 
making it more likely that a long-lived data structure will be 
allocated to a lower address within pool. This clusters the 


long-lived data structures together, leaving larger blocks of free 
pool available for more dynamic types of allocation. Although this 
can increase the effective use of available pool space, it also causes 
a noticeable increase in disk I/O as tasks are checkpointed. CLI 
tasks, ACP tasks, and tasks with outstanding buffered I/O are exempt 
from checkpointing while a high pool state exists. 


The remaining option concerns PMT's list of abortable tasks. During 
extreme fragmentation, PMT displays a list of abortable tasks and 
prompts for tasks to abort. By default, PMT does not list or abort 
privileged tasks running from the console terminal. You can override 
this default by modifying PMTBLD.CMD. There are, however, exceptions 
to this option. These exceptions, CLI tasks, ACP tasks, and the task 
loader, are never listed by PMT as abortable tasks. 


13.3.5.3 Controlling Pool Use - When a low pool state is in effect, 
PMT executes the default pool use controls described in Section 
T37343% You can suppress any of these controls by modifying 
PMTBLD.CMD and task building PMT again. 


13.3.6 Aborting PMT 


If you wish to terminate PMT, you can easily abort it. You must do 
one of the following to abort PMT: 


e@e Issue an ABORT command from a privileged terminal 


@ Issue an Abort directive from a privileged task 
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When you select either of these methods. PMT performs the following 
actions before it exits: 


@e Restores TKTN'’s special TCB pointer if PMT previously cleared 
the pointer and TKTN is still installed (see Section 13.3.4). 
This restores normal TKTN operations. 


e Prevents the Executive's pool monitor code from requesting PMT 
after PMT exits. This is done by clearing the special TCB 
pointer for PMT... as set by MCR INSTALL, DCL INSTALL, and 
VMR INSTALL commands. 


e Cancels any outstanding pool use controls that it may have 
imposed because of a low pool state. 


e Displays the following message at the console terminal: 
Remove and petosteli FAY to restore fool moniboarine 
"PMT..." aborted 


This indicates that PMT's special TCB pointer has been cleared 
so that the Executive can no longer request PMT to run. To 
restore the pointer, you must remove and reinstall PMT using 
MCR or DCL. 


13.4 THE SET /PLCTL COMMAND 


The SET /PLCTL command sets the pool limit parameters used by the 
Executive pool monitor code and PMT. The syntax, parameters, and 
parameter limits for the command are discussed in Chapter 10 and also 
in the RSX-11M/M-PLUS MCR Operations Manual. Basic guidelines for 
setting the four command parameters are discussed in the following 
subsections. 


During a low pool state, you can compare the values you set and the 
information that is output to the console terminal (see Section 
13.3.3.2) to determine whether the parameters require further 
modification. 


13.4.1 Low and High Pool Limits 

The first two parameters of the SET /PLCTL command establish the low 
and high pool limits. The Executive pool monitor code uses these 
limits to determine when major pool events occur. 


In general, you should set the low limit value to the least desirable 


pool level. This is a limit where your system's workload cannot 
increase without the risk of a pool resource deadlock. The 
appropriate value for this limit varies with each system. You can 
determine the best value by experimenting with various limits. The 


low limit defaults to 600(decimal) bytes. 


Set the high limit value to reflect the type of use your’ system 
receives. The high limit parameter essentially controls the point 
where a low pool state is transformed into a high pool. state. The 
high limit defaults to 1600(decimal) bytes. 
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If pool use fluctuates considerably, a limit set relatively higher 
than the low limit will tend to reduce the number of pool state 


transitions. If pool use is typically constant, a high limit set 
close to the low limit will quickly show critical changes in the pool 
state. Since pool needs and use vary, you should experiment with this 


parameter to determine the optimum value. 


13.4.2 Pool Fragment Size 


This parameter establishes the minimum size of the largest pool 


fragment. PMT uses this limit to determine when pool fragmentation 
problems exist. When the largest pool fragment is the minimum size or 
greater, a high pool state exists -- as far as fragmentation is 


concerned. A low pool state exists when the largest pool fragment is 
smaller than the minimum size. The lowest permissible size of the 
largest. pool fragment is 200(decimal) bytes by default. You should 
experiment with this parameter to judge the optimum value. 


Fragmentation is one of the more frequent and less desirable pool 
problems. Thus, the value that you specify for this parameter can 
have an immediate impact on successful pool monitoring. 


13.4.3 Base Priority for Nonprivileged Tasks 


This parameter establishes the base priority for nonprivileged tasks. 
The optimum value of this parameter is application specific, but 
defaults to 51(decimal). During a low pool state, PMT uses’ this 
parameter to restrict newly requested nonprivileged tasks from 
competing for memory resources (see Section 13.3.3). Only those tasks 
with a priority less than the specified base priority are _ so 
restricted. 
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THE SHUFFLER 


The Shuffler (SHF) is a privileged task designed to compact space in 
system-controlled partitions when a memory allocation failure occurs. 
The Shuffler operates only within system-controlled partitions and is 
available for the RSX-11M/M-PLUS operating systems, but is not 
available for unmapped systems or for RSX-11S. 


This chapter describes Shuffler interaction with the operating system. 
Briefly, it describes system-controlled partitions. In more detail, 
it describes Shuffler structure, ways to monitor the Shuffler, and 
Shuffler algorithms for the operating system. 


14.1 EXECUTIVE AND MEMORY USAGE 


Memory is the processor storage medium in which the Executive and 
tasks reside when executing. The Executive is the kernel of the 
operating system that interfaces the hardware system with other 
components of the operating system and with the user. 


The Executive brings a task into memory for execution and places’ the 
task in competition with other active tasks. When tasks are brought 
into memory, they are placed in a section of memory called a 
partition. Partitions are contiguous areas of memory in which 
executable tasks run; however, a common partition may be defined that 
contains only data or code. 


RSX-11M-PLUS supports only system-controlled partitions. 
RSX-11M supports three types of partitions: 

1. System-controlled partitions 

2. User-controlled partitions 

3. Common partitions 
User~controlled partitions and system-controlled partitions are used 
to load waiting tasks. User-controlled partitions accommodate only 
one task at a time. If you want to run multiple tasks within a 
user-controlled partition, you must define multiple subpartitions. 
System-controlled partitions accommodate as many tasks as possible at 
any one time. The Executive allocates available space in 
system-controlled partitions and creates the dynamic subpartition for 


each task. 


On RSX-11M-PLUS, tasks, device drivers, dynamic common regions, and 
static common regions reside in subpartitions of the system-controlled 
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partition. Static common) regions are resident libraries and resident 
commons and both may be shared by tasks for more efficient use of 
physical memory. Resident libraries contain code, and resident 
commons contain data. 


On RSX-11M, static common regions must be loaded into common 
partitions. A common partition is a dedicated area of memory that may 
be shared by tasks. Tasks, device drivers, and dynamic common regions 
created by memory Management directives must be loaded into 
subpartitions of the system-controlled partition. 


14.1.1 System-Controlled Partitions 


Only mapped systems support system-controlled partitions. A mapped 
system is a system with memory management. A task in a mapped system 
can run in any system-controlled partition large enough to contain it, 
and the Executive is responsible for allocating space in that 
partition. Refer to the RSX-11M/M-PLUS MCR Operations Reference 
Manual for detailed information on system-controlled partitions and 
memory management. 


The Executive allocates dynamic memory space for waiting tasks in the 
following manner: 


1. Uses a priority level of 1 through 250 to determine a waiting 
task's use of a system-controlled partition. A higher number 
indicates a higher priority. 


2. Begins at the base of the partition and searches for a _ free, 
contiguous area large enough for the waiting task. 


3. Creates a dynamic subpartition within the system-controlled 
partition. 


4. Eliminates the subpartition to free memory when the task has 
finished execution. 


In some instances, a waiting task cannot be loaded into a 
system-controlled partition because there is not enough memory space 
available. If there is not enough space to load a waiting task, the 
Executive uses checkpointing to make memory space available to the 
waiting task. 


To make room for a waiting task, the Executive searches the 
system-controlled partitions for one or more tasks with a lower 
priority than that of the waiting task. The Executive then 
checkpoints (moves) the task of lower priority from memory to disk to 
make room for the waiting task of higher priority. The checkpointed 
task is immediately placed in competition with other tasks waiting for 
residency. When the checkpointed task is reloaded, it continues 
processing from the point where it was interrupted. 


On RSX-lLIM-PLUS, the Executive keeps track of outstanding 1/0 on a 
partition-by-partition basis. Thus, the Executive may checkpoint 
subpartitions with dynamic common regions, static common regions, and 
task regions if there is no I/O pending. 


On RSX-11M, the Executive keeps track of outstanding I/O on a 
task-by-task basis. The Executive cannot easily determine to which 
partition outstanding I/O is directed. Therefore, RSX-11M can only 
checkpoint subpartitions with task regions. Common partitions and 
dynamic common regions created by memory management directives cannot 
be checkpointed. 
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14.1.2 Partition Fragmentation 


Checkpointing does not always create enough memory space to load a 
waiting task. This is a result of partition fragmentation. 
Fragmentation in system-controlled partitions occurs when tasks of 
various sizes are entering and exiting memory, or when, for example, 
device drivers are loaded in the middle of a system-controlled 
partition. Device drivers, which cannot be checkpointed, often create 
space between subpartitions and below subpartitions called fragments. 


Tasks with nonbuffered, outstanding I/O cause fragmentation of 
system-controlled partitions. Such tasks cannot be checkpointed. The 
Executive must wait for the task's I/O count to reach zero before the 
task can be checkpointed. While the Executive waits for the task's 
I/O count to reach zero, the task is blocked from execution to prevent 
the task from issuing more I/O requests that could delay the loading 
of the waiting task. The following lists the serious causes of 
fragmentation in system-controlled partitions: 


1. Device drivers loaded in the middle of a _  system-controlled 
partition 


2. Subpartitions that are connected to the IP11 driver 


3. Subpartitions that are connected to an interrupt vector by 
means of a CINTS directive 


4. Subpartitions with nonbuffered, long-outstanding I/O, and 
whose I/O count has not yet dropped to zero 


5. Regions that have been fixed by the Executive for a memory 
parity error 


6. Dynamic regions created by PLAS directives (RSX-11M only) 


If, for any reason, including fragmentation, the Executive is unable 
to load a waiting task into a subpartition, the Executive requests the 
Shuffler. The Shuffler moves subpartitions in system-controlled 
partitions in an attempt to create the free space necessary to load a 
waiting task. Thus, the Executive requests the Shuffler only when all 
other attempts to load a waiting task fail. 


14.2 SHUFFLER PERFORMANCE 


The Shuffler is approximately 700(decimal) words and can be installed 
only on a mapped system. The Shuffler is installed during system 
generation by a VMR command and by default is built for the partition 
SYSPAR, which can also be used by the MCR dispatcher and TKTN. Refer 
to the RSX-11M or RSX-11M-PLUS System Generation and Installation 
Guide for more information on installing the Shuffler. 


The overhead incurred for the Shuffler task is found in the Shuffler, 
not in the Executive. The Shuffler responds well on a system if there 
are fewer tasks loaded in memory and if the Shuffler does not execute 


frequently. If you have a heavily loaded system, the Shuffler may 
execute more than you want because of repeated memory allocation 
failures. If the Shuffler executes frequently on your system, better 


performance is obtained when the Shuffler is fixed in its own 
partition where it does not have to compete with MCR and TKTN for 
memory. 


The word, S$SHFTM, in the Executive's system common area limits the 


number of times the Shuffler may be requested within a time interval. 
SSHFTM heightens the Shuffler's effectiveness on your system. Each 
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Y 


time the Executive requests the Shuffler, this timer is checked. If 
the timer registers zero, the Shuffler may be requested. If the timer 
registers a positive number, the request for the Shuffler is ignored. 
The amount of time (clock ticks) that must elapse before the Shuffler 
is requested again is stored in the system common area, $SHFCT. When 
the Shuffler is successfully requested, $SHFTM is initialized for the 
new interval with the value stored in S$SHFCT. 


If you are a privileged user, you may change S$SHFCT. To change 
SSHFCT, you need a copy of RSX11.MAP, the Executive map produced 
during system generation. Using the map, you must determine’ the 
address of the global symbol SSHFCT. You can change the contents of 
the system S$SHFCT with the MCR OPEN command. The Shuffler is 
requested infrequently if the value is set too high. If the value is 
set too low (zero), system response may decrease because the Shuffler 
is being requested too frequently. 


14.2.1 Monitoring The Shuffler 


Several memory allocation failures during peak usage periods result in 
the repeated request of the Shuffler. The repeated execution of the 
Shuffler can produce a noticeable decrease in response time. You may 
monitor the Shuffler's effect on your system by using RMD. RMD is a 
privileged task that displays information concerning task activity on 
the operating system. Refer to Chapter 6 for a detailed explanation 
of RMD. 


If you want to monitor Shuffler activity with RMD, you must dedicate a 
video terminal on which to run the RMD display. The key features to 
monitor on the memory display page are as follows: 


@e The currently executing task; *IDLE* indicates that no task is 
executing 


@ The number of active tasks in memory and the amount of memory 
they occupy, plus the number of active tasks checkpointed (on 
disk) and the total memory they would require. 


These features show task activity. If the Shuffler is active, tasks 
are moving down in the partition, and the currently executing task 
field registers the Shuffler as the active task. 


Occasionally, the Shuffler registers as the active task, but tasks 
cannot be seen moving down in the partition. To verify that tasks are 
not moving when the Shuffler is executing, check the number of active 
tasks checkpointed (on disk) and the number of tasks waiting for 
memory. If this count remains the same over a period of time, the 
Shuffler is executing but cannot create enough space for waiting 
tasks. Thus, the Shuffler is using too much of the_- system's 
resources. If the system does not recover, it might be better to 
abort the Shuffler from your system. 


If the Shuffler task continues to use too much of the_ system's 
resources, you should remove the Shuffler from your system with the 
MCR REMOVE command. 


14.3 THE SHUFFLER ALGORITHMS 


When a memory allocation failure occurs, the Executive requests the 
Shuffler. The Shuffler searches memory for a_esystem-controlled 
partition that has at least one task waiting for space. When the 
Shuffler locates such a system-controlled partition, it attempts to 
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move (shuffle) subpartitions in the memory partition to create the 
continuous area necessary to load waiting tasks. 


On RSX-11M, the Shuffler can only shuffle task subpartitions. Because 
RSX-11M does not maintain an outstanding 1/0 count on a 
partition-by-partition basis, the Shuffler cannot determine whether 
outstanding 1/0 is pending to a common partition or a dynamic common 
region. Thus, the Shuffler does not shuffle common partitions or 
subpartitions with dynamic common regions created by memory management 
directives. 


On RSX-11M-PLUS, the Shuffler does shuffle ‘common regions — ‘because an 
outstanding I/O count is maintained ition-by-partition basis. 
‘Thus, subpartitions containing sta “commo regions or dynamic = 
regions can be shuffled when there is no 1/0 pending. = 


The Shuffler uses two algorithms to move subpartitions in memory. 
Each algorithm executes several steps repeatedly until the partition 
reaches a stable state. 


14.3.1 The First Pass Algorithm 


In the first pass, the Shuffler attempts to move each subpartition to 
the base of the partition. When subpartitions are moved to the base 
of the partition, free space is created at the top of the partition so 
that a waiting task can enter memory if there is enough space. 
Shuffling occurs in the following steps: 


l. The Shuffler requests the Executive to unconditionally 
checkpoint all stopped checkpointable subpartitions and 
checkpointable subpartitions that have been blocked with a 
CLI command. 


2. The Shuffler attempts to move each subpartition to the base 
of the partition and blocks each executable task from further 
execution. If a subpartition has outstanding 1/0, the 
Shuffler waits for the task's nonbuffered, outstanding I/O 
count to reach zero. If the I/O count does not reach zero in 
approximately .5 seconds, the Shuffler marks the subpartition 
as having outstanding I/0, and restarts the first pass 
algorithm. The Executive clears the subpartition's I/O 
indicator when the task's I/O count becomes zero. 


3. The Shuffler moves each task to the base of the partition. 
If the subpartition's I/O count reaches zero within 30 
seconds. 


4. Each subpartition is unblocked to allow further execution 
after shuffling is complete, and the free space, now above 
the subpartition, is deallocated. 


Be aware that a fixed task can be shuffled. If you do not want to 
have a fixed task shuffled, you must fix this’ task in a 
user-controlled partition or in its own dedicated system-controlled 
partition. 


If fragmentation has not occurred at the end of the first pass, it 
means the Shuffler has successfully merged the free space in the 
partition into one continuous area at the top of the system-controlled 
partition. A task may then be loaded into memory if there is enough 
space available. 
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However, memory space may not be available if there are several tasks 
already loaded in memory, or if fragmentation is dividing the 
system-controlled partition into two or more partition sections. A 
partition section is a subset of the area in a system-controlled 
partition. Each partition section is flanked on at least one side by 
a subpartition that cannot be shuffled. For example, if a device 
driver is loaded in the middle of a system-controlled partition, the 
system-controlled partition is divided into two partition sections 
because a device driver is a subpartition that cannot be moved. 


If, during the first pass algorithm, the Shuffler encounters a 
subpartition that cannot be moved, the Shuffler begins to shuffle 
subpartitions that can be moved to the base of the partition section 
that bounds it. The Shuffler cannot shuffle subpartitions around a 
subpartition that cannot be moved. Therefore, if fragmentation has 
occurred during the first pass, the system-controlled partition is 
divided into two or more partition sections, and the free space in the 
partition may no longer be merged at the top of the partition, but 
rather at the top of the partition section. 


The Shuffler initializes the second pass algorithm if enough memory 
space is not available for waiting tasks, or if fragmentation has 
divided the system-controlled partition into several partition 


sections. Little memory space or partition sections prevent the 
Shuffler from accumulating all the free space at the top of the 
partition. The free space in each partition section is separate and 


cannot be merged with the free space in another partition section. 


14.3.2 Second Pass Algorithm 


The second pass algorithm is executed once for each partition section 
within a system-controlled partition. This pass attempts to create a 
reverse priority list of subpartitions that can be checkpointed by the 
waiting task. 


During the second pass, the Shuffler creates a list in ascending 
priority order of the subpartitions in each partition section. The 
Shuffler then compares the size of the waiting task with the sum of 
free space in the partition section plus the total of one or more 
lower priority, checkpointable tasks. If the waiting task is smaller, 
the Shuffler requests the Executive to checkpoint the lower priority 
task(s). 


Checkpointing the lower priority task(s) may create new space, but the 
new space may not comprise a continuous area in memory. The Executive 
may begin the first pass algorithm to accumulate the free space of the 
partition section. The free space is then allocated to the waiting 
task. As long as there are subpartitions that cannot be moved in a 
system-controlled partition, memory is still divided into two or more 
partition sections. 


If the Shuffler completes the second pass without finding room for a 
waiting task, the Shuffler searches for the next system-controlled 
partition with waiting tasks. If there are no other system-controlled 
partitions with tasks waiting for memory space, the Shuffler exits. 
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RSX-11M-PLUS SYSTEM RECONFIGURATION 


A reconfigurable system is a system in which you can add or remove 
system resources such as memory and devices. Reconfiguration is a 
means of physically and logically connecting and disconnecting various 
resources. This chapter discusses the purpose and application of 
reconfiguration, and describes the components and commands of the 
reconfiguration services. 


System reconfiguration is available only on RSX~11M-PLUS'- systems. 
Some of the information in this chapter, however, applies only to 


multiprocessor systems. Blue ink is used to distinguish this 
information. 


15.1 THE RECONFIGURATION SERVICES 


The reconfiguration services allow you to reconfigure an RSX-11M-PLUS 
system to bypass faulty hardware elements and to isolate the system 
from the effects of these elements. 


With the reconfiguration services, you can define a set of hardware 
resources that are accessible from the on-line system and also remove 
devices from the pool of resources allocated to the on-line system. 
For example, after bootstrapping the system, you can place a failed 
disk drive off line and then use another drive that is already on line 
or place one on line to take over for the disabled unit. 


15.1.1 Reconfiguration Components (CON,RD:,HRC) 1 


You reconfigure system resources by using together a command interface 


(CON), a loadable driver (RD:), and a privileged reconfiguration task 
(HRC). CON and HRC must have enough checkpoint space allocated for 
them both to be resident in memory at the same time. If the operating 


system cannot load both tasks at the same time, CON commands will 
fail. 


CON, as the command interface, receives and parses the commands” that 
you issue to reconfigure the current system. CON then creates and 
submits QIO packets to the reconfiguration driver (RD:). 


RD:, the reconfiguration driver, serves as an interface between a user 
task (either CON or a user application task) and the HRC task; it is 
the gateway between tasks that generate reconfiguration requests and 
the actual implementation of those requests. RD: accepts QIO packets 


1. DIGITAL will accept SPRs regarding the interface, but reserves the 
right to treat such SPRs as informational only. 
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from any task and places these packets into the receive queue of HRc. 1 
Before passing the QIO packets to HRC, RD: performs privilege and 
address boundary checks on them. The checks ensure that the packets 
are using valid addresses and legal function codes, and, for some 
functions, that RD: is attached to them. 


HRC, the privileged reconfiguration task, performs the actual 
reconfiguration operations for the system. To process reconfiguration 
requests, HRC calls Executive routines, which then call the associated 
device drivers. HRC services the requests for configuration 
information by passing the desired information directly to the user 
buffer. 


After HRC services the request, a status is returned (by means of I/0 
completion) to the requesting task. The status return was implemented 
in part to allow tasks other than CON to interface with HRC. 


The data base for each system device contains status words’ that 
reflect device state. When you change a system device state, HRC 
modifies the appropriate data base status word to either grant or 
inhibit device access. 


15.1.2 Device States 


The RSX-11M-PLUS system reconfiguration services control the 
configuration state (on line or off line) of the hardware devices and, 
therefore, control device access. A system device can assume one of 
four states: 


1. On line - device on line, access granted 
2. Off line - device off line, access denied 


3. Marked for on line - device will be brought on line when 
access path exists, access denied 


4. Marked for off line - indeterminate state, access denied 


In the on-line state, a device is logically on line for access. This 
state indicates that an access path exists between the device and an 
on-line processor and that a call (if any) to the driver's controller 
or unit status change entry points was successful. RSX-11M-PLUS 
grants access to on-line devices only. To access an on-line disk or 
tape volume and perform virtual I/O on it (for example, read or 
write operations to files), the volume must be mounted. (See the 
RSX-11M/M-PLUS MCR Operations Manual or the RSX-11M-PLUS Command 
Language Manual for a description of volume access rights and mounted 
volumes. 


1. Note that programs written to use the current version of RD: may 
have to be modified in the next release. You should centralize all 
code concerning RD: so that modifications can be made easily. 


Because of the likely changes, RD: has not been documented. For some 
information, check the reconfiguration sources located in UFD [27,10] 
of the distribution kit (except the RLO2 kit, which does not contain 
any sources). Important modules for the interface are CNHRC, HROOT, 
and HRSUB. (See also the macro OLRDF$S in [1,1]JEXEMC.MLB for a 
description of volume access rights and mounted volumes.) 
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When a device is in the off-line state, the system denies access to 
the device. Attempts to access an off-line device result in an I/O 
error (IE.OFL). (See the RSX-11M/M-PLUS and Micro/RSX I/O Operations 
Reference Manual for lists and explanations of error codes.) Taking a 
controller off line also takes all of its associated units off line, 
which places the units in the marked for on-line state. 


The marked for on-line state indicates that a request to bring a 
device or controller on line has been made, but part of the access 
path to the device or controller is off line. Access attempts yield 
the error code IE.OFL. HRC places a device marked for on line 
logically on line when it brings the entire access path on line. 


The marked for off-line state indicates that the system encountered an 
unexpected error in attempting to place a specific device logically on 
line. You must issue an explicit off-line command before attempting 
or retrying an on-line operation. 


15.1.3 Placing Devices Logically On Line and Off Line 


To place a device logically on line, HRC first verifies that the 
device driver is loaded (for loadable drivers only) and then tests 
whether the controller can access the device (the controller must _ be 
on line). If the controller can access the device (an access path 
exists), HRC modifies the appropriate status word to reflect that the 
device is on line. If the controller or device cannot be accessed, 
HRC marks the device for on line and then places the device on line 
when the access path is brought on line. 


Before placing a device off line, HRC attempts to protect against 
inadvertent loss or possible corruption of data by verifying that the 
state change will not interfere with active I/O. HRC considers a 
device active and rejects off-line commands if the device has context. 
The reconfiguration services define device context as a condition that 
indicates (or permits) I/O activity on the device. The following is a 
list of conditions that define device context: 


e A task is attached to the device (for example, the print 
despooler attaches the line printer). 


e The device (or an associated device) is a logged-in terminal. 


e The device (or an associated device) contains a mounted 
volume. 


@ For the DTO7 bus switch, a port is logically connected to a 
processor (linked). 


@ For memory boxes, the memory within the box is logically on 
line (multiprocessor systems only). 


@e A disk device has data caching enabled. 


You cannot take a controller off line if any of the units on the 
controller have context. 


For dual-port disks (RKO6/RKO7, RMO2/RMO3/RMO5/RM80/RPO7, and 
RPO04/RPO5/RP06), which have each port connected to a different 
controller, you can place off line one path with context as long as 
the alternate path is on line. (See the description of the OFFLINE 
command for more information.) 
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15.2 INITIATING THE RECONFIGURATION SERVICES 


You reconfigure an RSX-1L1IM-PLUS system interactively from a terminal 
or by means of indirect command files. The reconfiguration services 
act as an interface between your terminal and the RSX-11M-PLUS system. 


To issue a reconfiguration command, type a command line in response to 
the default prompt (>) or to the explicit command interface prompt 
(CON>). A command line consists of three components: a command name, 
any required parameters, and a line terminator. (Note that there is 
no DCL command to access CON.) 


15.2.1 Invoking CON 


It is not necessary to use the entire command name when issuing a 
command line; CON requires only the first three characters of the 
name. However, to make the intent of the command input clear to 
someone reading a printed copy, you can use the entire command name. 
For example, you can issue the ONLINE command as follows: 


Formats 


CON>ONL dev-spec 


or 
CON>ONLINE dev-spec 
dev-spec 
The target device. 
(RET) 
The RETURN key (the line terminator). 
A space or tab signals the end of the command name. Therefore, no 


spaces or tabs are permitted within the name itself. To use the 
reconfiguration services, first invoke the command interface CON and 
then issue the commands. There are two ways to invoke CON 
interactively: 


1. Use the one-line format to invoke CON, execute a_e single 
command, and return control to MCR. For example: 


MCR OS CON commence) ire ED 
2. Use the direct task format to invoke CON and obtain a task 
prompt (CON>). For example: 


MOR oT 


eA es 


Type CTRL/Z to exit from the direct task format. 


You can also enter commands through indirect command files. An 
indirect command file that contains reconfiguration commands does not 
require terminal interaction when the file is executed. Thus, 
indirect command files are a convenient means of creating 
configuration command sequences that create different configurations 
or restore previous configurations. 
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For example: 


NMCROCON BCONFE TG 


This command line invokes CON, executes the reconfiguration commands 
contained in the indirect command file CONFIG.CMD, 


to MCR. 


The following command line executes the commands in the file 


CONFIG.CMD and returns control to CON: 


CON? ACOMP TG 


Indirect command files can be nested to a maximum depth of three. 


15.3 CON COMMAND SUMMARY 


The following table summarizes the reconfiguration commands’ and 
provides a compact overview of the commands. Detailed command 


descriptions appear in alphabetical order in Section 15.4. 


Table 15-1 


CON Command Summary 


BUILD 


CLEAR 


DISPLAY 


STATUS 


HELP 


IDENT 


LINK 


LIST 


OFFLINE 


Creates a command sequence in an internal 
buffer that, if executed, duplicates the 
current system configuration. 


Erases the command sequence created by 
BUILD (but not the file created by LIST) 
that is stored in the internal buffer by 
CON. 


Displays the configuration and status of 
the hardware devices in the current 
system. 


Emits the current status of a specific 
device. 


Displays the help text for CON. 


Displays the current versions of CON and 
HRC and the date and time the two tasks 
were built. 


Logically connects a port of a switched 
bus run to a processor. 


Displays the results from a BUILD command 
or puts the command sequence into a 
specified file. A file type of .CMD is 
suggested because that is the default 
type for an indirect command file. 


Removes a device without context from the 
active set of devices in the current 
configuration. 


(continued on next page) 
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OFFLINE MEMORY 


ONLINE 


ONLINE MEMORY 


SET 


SWITCH 


UNLINK 


Table 15-1 (Cont.) 
CON Command Summary 


(Multiprocessor systems only.) Removes 
the memory box with the highest addresses 
from the system. Note that you must 
first ensure that nothing is using the 
nemory in the memory box. 


Attempts to place a device logically on 
line. 


(Multiprocessor systems only.) Adds a 
memory box to the on-line configuration. 
Note that you must expand the partition 
structure to use the additional memory. 


Alters the CSR or interrupt vector 
address values of a device and, on 
multiprocessor systems, activates or 
inhibits the sanity timer and its alarm. 


(Multiprocessor systems only.) Logically 
disconnects a port of a switched bus run 
from a processor and then connects’ the 
port to another processor. The command 
is equivalent to a LINK command followed 
by an UNLINK command. 


Logically disconnects a port of a 
switched bus run from its respective 
processor. 


CON also accepts two switches, /HE and /NOMSG. These switches are 
used alone in the CON command line. Their functions are as follows: 


/HE 


/NOMSG 


Displays the help text for CON. 


Suppresses all information displays and 
error messages returned by CON. You must 
exit from and then reenter CON to have the 
messages displayed again. 
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BUI 


15.4 CON COMMAND DESCRIPTIONS 


This section describes each of the reconfiguration commands. Note 
that some of the commands must be issued from a privileged terminal. 


BUILD 


The BUILD command creates a sequence of commands that, when executed, 


duplicates the current system configuration. The sequence of 
reconfiguration commands resulting from a BUILD command is held in a 
buffer in memory. When this sequence of commands executes, the 


reconfiguration commands’ restore the system to the exact state 
existing when the BUILD command was issued. 


Format 


CON>BUI[LD] 


Example 


CUA BOT D 


This command creates a sequence of commands that duplicates the 
current system configuration. 
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CLEAR 


CLEAR 


The CLEAR command erases from the internal buffer the current sequence 
of commands created by the BUILD command. The command does not delete 


the file created by the LIST command (described later in this 
section). 


Format 


CON > CLEAR 


Example 


COM BUT 
CONS CLEAR 


The CLEAR command removes from the internal buffer the 


command 
sequence resulting from the previous BUILD command. 
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DISPLAY 


DIS 


The DISPLAY command provides current system configuration information 
about the device units, device controllers, processors, memory boxes, 
and memory box controllers. 


Format 


CON>DIS[PLAY] [keyword(s)] [FOR string] 


Keywords 

UNI[TS] 
Displays every device unit in the current configuration. 
The display equates each device unit with its respective 
controller. 

CON[TROLLERS ] 
Displays every device controller in the current 
configuration. 

FUL[L] 


Displays the status flags for every device unit and device 


controller 


in the current configuration. The status flags 


indicate the following: 


Accpath 


Context 


Driver 


Massbus 


Multiport 


Offline 


Online 


Prv-Diag 


Unknown 


The device has an on-line access path. 


For a tape or disk (mountable device), the 
device contains a mounted volume. For a 
terminal, a user is logged in. Other devices 


are attached. 


For a device unit, the driver is loaded. For a 
device controller, a driver is available. 


The device is connected to an RH MASSBUS 
controller. 


The device is dual-ported (a dual-access 
device) between two controllers (for example, a 
dual-ported RPO6 drive). 


The device is off line. 

The device is on line (or marked for on line). 
(Used with the OFFLINE and ONLINE keywords.) 
The device is marked for on line or off line, 
but nothing can happen until the respective 
controller is brought on line or taken off 


line. 


The CSR assignment for the device is 160000 and 
thus cannot be accessed. 
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ALL 


Same display as for the FULL keyword with the addition 


of 


interrupt vector addresses and CSR assignments for device 


controllers. 


ATTCRIBUTES ] 


Displays interrupt vector addresses and CSR assignments 


device controllers. 


The DISPLAY command allows more than one keyword per 
line. However, some combinations (such as DISPLAY UNITS 


DB) are meaningless. The DISPLAY command ignores 


inappropriate keyword. 


If the command omits a keyword, the display contains the 


for 


command 
FULL FOR 
an 


logical 


names and status flags for every device unit and device 


controller in the current configuration. 


FOR string 


An optional parameter that allows a selective display of 


a 


particular device or device group. When you use this parameter, 


CON displays the requested information for the devices s 
in the string. 


You can also use one or two wildcard characters (*) 


pecified 


in the 


string. You use one wildcard to find out which devices are 


connected to the controller you have specified aft 
wildcard. You use two wildcards to find out which devi 
the attribute you have specified after the wildcards 
ONLINE or OFFLINE). 


For example: 
CON>DIS FULL FOR RH 

This command displays all of the RH controllers. 
CON>DIS FULL FOR **ONL 


This command checks to see which devices have the 
attribute (port-specific status is not displayed). 


Examples 


CONSTISELAY FULL FOR IB 

DBO3 OfflinesMultirortsMasshbusrAccrathryIriver 
FORT DROA RHEO: Online 

FORT DBOB RHCO$ OnlinersCurrentsAccrath 
DBL: OfflinerMultirortyMasshusrAccrathryUriver 
FORT DRLA RHE1I: Online 

FORT OBR RHCL? NnlinerCurrentrsAccrath 


This command displays information about all of the 
devices configured into the system. 
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DIS (Cont.) 


CONSTISPLAY UNITS 

DBO? RHBG? sRHOG 
VEILS RHE TS 2 RHO? 
TRO RHAG? 
DRL BHAT $ 
MMO PATIO 
MHD 4 


bf Fh Fo tH ae 
ce oe 


TTsSt YL Ad? 

: YRZAGE 

tT34 YZALE 
s 


wen 3 
(ZARE 


DRAGS 
Qe QS ds 


VLG. TL AO 3 
LPO. LPAQ SE 
Lies Ne op aes 
Less LFCOS 
ALG: 

MOY MAG 


Mts aMAad t 


This command displays all of the device units and controllers 
configured into the system. 
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ESTAT 


ESTATUS 


The ESTATUS command causes CON to exit with its exit status word 
reflecting the current status of a specified device. Used with the 
Indirect Command Processor (Indirect; see the RSX-11M/M-PLUS Indirect 
Command Processor Manual), the ,command returns a 16-bit word 
describing device status. You can use the status word to obtain 
information about the configuration. The meanings of the bits in the 
word are given in Table 15-2. Note that the meanings for units and 
controllers are different from those for ports. 


Table 15-2 
Exit Status Values for CON ESTATUS 


If the status is for a unit or controller: 


Bit Bit 
No. Value Description Display 

0 1 Exit status value: 

1 2 O = Warning 

2 4 1 = Success 

2 = Error 
4 = Severe error 

6 100 This is a subcontroller device. 

7 200 This is a controller device. 

8 400 O-device is on line, l-device is Online 
off line. Offline 

9 1000 This device is restricted to privileged Prv Diag 
and diagnostic functions. i 

10 2000 This is a multiport device. Multiport 

11 4000 This is a MASSBUS device. Massbus 

12 10000 This device's CSR is 160000 Unknown 
(unknown). 

13 20000 This device has an on-line access Accpath 
path. 

14 40000 This device has context. Context 

15 100000 A driver is loaded for this device. Driver 


If the request is for a port: 


Bit Bit 
No. Value Description Display 
0 1 Exit status value (see above) 
1 2 
2 4 
8 400 O-port on line, l-port off line. Online 
Offline 
10 2000 This is the current port. Current 
13 20000 There is an on-line access path to Accpath 
this port. 
14 40000 This port or the device it services Context 


has context. 
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Example 


"OTL ! Invoke Indirect, 
AT.>- ENABLE SUBSTITUTION |! Enable substitution mode. 
AT.2CON ESTAT [DBI ' Tyre CON command line. 
>CON ESTAT UB1: i System disrlays command line. 
' 
| 
\ 


AT srs (EXSTAT?’ Reauest contents of <FXSTAT> to he disrlayed, 


79126401 System disrlays current <EXSTAT> contents. 
AT.2°Z Exit Indirect 


2@ <EOF> 


Using Indirect interactively, the CON command line emits’ the 
current status of DBl:, which is stored in the Indirect special 
symbol <EXSTAT>. 


The number 126401 has the following meaning: 


100000 Device's driver loaded. 
20000 Device has on-line access path. 
6000 Device is both multiport and MASSBUS. 
400 Device is off line. 
1 Exit status value = Success. 
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HE 


HELP 
The HELP command displays the help text for CON. 
Format 
CON>HE[LP ] 
Example 
CON? HELF 


CON -- Configuration Control Command Task. 
Imrlemented commands? 


ONLINE <cevice list 

ONLINE MEMORY «memory w.box> 
ONLINE ALL 

OFFLINE <devicellist > 
QFFLINE MEMORY <memors.box> 
OFFLINE ALL 


SET <controller.ise 


wh 


(User typed CTRL/O to suppress further output.) 


This example shows the form in which the HELP command displays 
information about the system configuration. 
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IDENT 


IDENT 


The IDENT command displays the current version numbers of the CON and 
HRC tasks. The date and time the tasks were task built are also 


displayed. 
Format 
CON>IDENT 
Example 
CONS INENT 


CON ~- CONFIGURE Version 4.00 
Task muilt?: T-QEC-85 12°52243.5 


HRC -- HRC Version 094,000 
Task muilt? WS-NEC-85 23°359°10.9 


In this example, Version 4.0 of CONFIGURE was task built on 
December 1, 1985; Version 4.0 of HRC was task built on December 


15, 1985. 
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LIN 


LINK 


The LINK command logically connects a port of a switched bus run to a 


processor and thus permits access to the devices on the switched 
segment of the bus run. 


To logically connect a switched bus run to the processor's UNIBUS, the 
devices on the switched segment must all be off line or marked for on 
line. You cannot dynamically link switched bus runs. 


Format 


CON>LINK UBx TO CPx 


UBx 
The target-switched bus run. Switched bus runs are named _ using 
the designation UB followed by a letter from the DIGITAL hardware 
alphabet as follows: UBE, UBF, UBH, UBJ, UBK, UBL, UBM, UBN, 
UBP, UBR, UBS, and UBT. 

CPx 
The target processor. 

Example 


CON=LINK URE TO CFA 


This command logically connects the first switched bus run (UBE) 
to processor A (CPA). 
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LIST 


LIST 


The LIST command displays the current command sequence or writes’ the 
sequence to a file. You can use this command to keep a list of the 
commands that will duplicate the current configuration. If the buffer 
in which the current command sequence is stored (see the description 
of the BUILD command) is empty, CON returns the following message: 


CON -- Command list is empty. Nothing to print 


If you specify a .CMD file type, you can execute the commands from the 
indirect command file (that is, BUILD, LIST filename.CMD, @filename) 
and then return to CON. : 


Format 
CON>LIST [filespec] 
filespec 


Any legal RSX-11M-PLUS file specification in the form 
ddnn:[g,m]filename.type; version. 


Example 


CONS BUT LY 
CONSL IST 
CNLINE RHA 
QHEL INE HB 
QANLGME PHO 
Cee Tie A 
OFFLINE VLA 
ML INE ¥ZA 
DAL LAE DRA 
GONE INE [LA 
ONLINE LFA 
QNLIRE TRG? 
ONETNE TBA? 
CNL TNE TRG? 
ONLINE TRIE 
UMLIME MMO 
ONLINE MM1: 
ONLINE COO$ 
ONLINE TTO? 
QNLINE TTL; 
DALINE TT2¢ 
QWLINE Tae 
ONLINE TT4¢ 
ONLINE TTS3 
OMLtNE TTét 
ONLINE TT?$ 
ONLINE TTiO? 
QNLINE UKOS 
ONLINE URLS 
QAL INE tbo: 
UNIINE LPOS 
WALINE NLOS 
QNIINE MO? 
ONLINE TM; 
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In this example, the BUILD command creates a sequence of commands 
that duplicates the current system configuration. Next, using 
the LIST command displays the sequence of commands you would use 
to reestablish the current system configuration. 
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OFF 


OFFLINE 


The OFFLINE command changes the state of a inactive device to 
off-line, thus removing the device from the active set of resources in 
the current system configuration. This prevents further device 
access. To take a device off line, it must not have context (see 
Section 15.1.3), and HRC must be able, in 1000(decimal) tries or less, 
to detect when there is no I/O activity in progress. 


The transition to the off-line state for a specific device controller 
is completed only if all associated devices are also off line. If an 
associated device is not off line, HRC rejects the OFFLINE command 
because placing the device off line could interfere with active I/0. 


Issue the appropriate MCR command(s) to remove device context. This 
ensures that the device does not have context and can be placed off 
line. 


If a task has attached the device unit, the task must be detached (or 
request to be aborted) before the unit can be placed off line. For 
example, if you issue an OFFLINE command for a line printer controller 
(such as OFF LPB), and a connected unit (such as LP1l:) has context (in 
this case, LPl: is a spooled device and attached by the Queue 
Manager), CON rejects the command and issues the following error 
message: 


weenie to take unit with cantent effline 
If the device is marked for on line (for example, a device unit with 
its controller off line), the command changes the device state to 
off-line. Subsequently, when the controller is brought on line, the 


system does not activate the device. 


If the device is marked for off line, the command changes the device 
state to off-line and thus enables a future on-line attempt. 


Individual ports of dual-port devices can be taken off line 


separately. You may want to do this if the port does not work 
correctly (for example, you cannot access the device through the 
port), or if you want to increase system throughput. Figure 15-1 is 


an example of the way throughput could be increased: 


RHB 


RHA 


ZK-575-81 


Figure 15-1 Sample Configuration for Increasing System Throughput 
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OFF (Cont.) 


With this configuration, it is probable that the system will use the 
DBOA port. Because activity on DBl: must use the DBIA port, it has 
to wait until DBOA is free. If you put only ports DBOB and DBI1A on 
line, each DB disk has its own controller and does not have to wait 
for another port to be free. 


The OFFLINE command also accepts an optional keyword, ALL, which 
places off line all devices except the system disk and the terminal 
that issued the command. (The OFFLINE ALL command is useful prior to 
a system save.) Before issuing the OFFLINE ALL command, you must first 
dismount all volumes (tapes and disks) except the system disk and log 
out all terminals except the issuing terminal. 


Formats 
CON>OFF[LINE] device-specl[ ,device-spec2...,device-specn] 
CON>OFF[LINE] ALL 

Note that device-spec also includes processors (CPx). 

Requirements 
@e Only a privileged user can modify the system configuration. 
@e No tasks are attached to the device. 
@ No volumes are mounted on the device. 


e If the device is a terminal, no users are logged in on it. 


COOP PL TARE Leash Pot 


CONSOPF Y742¥ TRY 7O. Veh 1 ferminels assumed mot loesed in 


The command sequence logically places the devices off line, which 
allows the bus run UBE to be placed off line. 


£5=20 


RSX-11M-PLUS SYSTEM RECONFIGURATION 


OFF MEM 


OFFLINE MEMORY 


(Multiprocessor systems only.) The OFFLINE MEMORY command removes a 
memory box from the system configuration. Because memory must be 
contiguous, the target box must be the memory box in the system 
configuration with the highest addresses (the last memory box added to 
the system). If the target box is not the last box in the memory 
configuration, CON rejects the command and issues the message: 


HERE Them oh beak. bate oP P Dime. Hat Pes h dyes th tmemores 


If a partition maps to a memory box targeted for off-line status, CON 
rejects the command and issues the following message: 


ot de 1 To ae oe, is S| = © 1g oe ’ Ps oer as Ge eee ta hse, bere ; acs a ar oo : we eee oe ae: carvan 
SEMRO. .. Mant’ bh Labbe ioe offline. Partlrhion overmnease mink 


Therefore, you must contract the partition structure before removing 


the memory box. The MCR SET /TOP command can adjust the partition 
structure up or down (see the RSX-11M/M-PLUS MCR Operations Manual for 
details), but it is your responsibility to ensure that nothing is 


using the memory in the memory box. The system is protected so that 
you cannot bring the memory box off line if anything is using it. 


Format 


CON>OFF[LLINE] MEM[LORY] memory-box 


Example 
cre QFE 4EM MKD? 
This command removes memory box MK2: from the system 
configuration. 
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ONLINE 


The ONLINE command changes the state of a device to on line and 
enables device access. 


The transition to the on-line state is completed only if an access 
path exists between the device and the processor, and if the device 
driver can successfully initialize the device. 


If the device lacks an access path, the ONLINE command changes device 
state to marked for on-line; the device is activated when an on-line 


access path becomes available (when the controller is brought on 
line). 


The ONLINE command also accepts an optional keyword, ALL, which places 
logically on line every device controller and device unit known to the 
system. 


Note that the data base values for interrupt vector and CSR 


assignments have no effect on the system until the device is brought 
on line. 


Formats 


CON>ONLLINE] device-specl[ ,device-spec2...,device-specn] 
CON>ONL[INE] ALL 


Requirements 


@e Only a privileged user can modify the system configuration. 


e The specified device must be physically present in the target 
system and included in the system at system generation. 


e If the specified device is serviced by a loadable driver, the 
driver and device data base must be loaded. 


The ONLINE command activates a device unit only if the associated 
controller is on line. The command first tests the unit to determine 
whether it actually exists on the controller and then performs drive 
sizing to determine device unit type. If the unit exists, it is now 
ready for user access. If the associated controller is off line, the 
command marks the unit for on-line status; it is presence-tested and 
sized when the access path is completed and, if present, activated. 


To activate a device controller, the ONLINE command tests’ the 


controller's status register (CSR) to determine whether it is 
physically present. If the controller is present, then all of the 
associated units that are marked for on-line status are 


presence-tested, sized, and brought on line. Off-line units remain in 
the relative off-line state regardless of any ONLINE command performed 
on the associated controller. 


To activate a processor on multiprocessor systems, the OhLINE command 
tssues a DoOoEStrap request to the target processor. PP fhe Laraqek 
processor iyjnores the boots’ rap request or canno DOE puceress Fully, 
CON issues the following mnessade fafter a time-ont of 3 seconds)> 


tog “ Pare 
SAAT Sm. tees feh eta be Pro, el tates if PL aye 


L5=22 


RSX-11M-PLUS SYSTEM RECONFIGURATION 


ONL (Cont.) 


You can also bring on line individually the ports of a dual-port 


device, thus increasing system throughput because you do not have to 
wait for both ports if one does not work. 


For dual-port terminals, you need a Status Control Block (SCB) for 
each terminal to bring the ports of dual-port terminals on line 
individually and to switch them individually. To switch the ports, 
the software will bring the controller on line, but the terminals must 
be switched manually using the CS1l switch on each terminal. If you 
have only one SCB for each controller, all of the terminals ona 
controller have to be switched over to the same controller. 


Examples 


The following command sequence (used on a multiprocessor system) 
assumes that the UBE bus run has been switched from CPA to CPB. 
The commands place the software bus devices on line for access: 


CONSONLINE LPAsLFO? 1 On line Line Frinter and controller 
CONSONL YZA*YZR*eYZCrYZNI ! On line terminal interfaces 
CONSONL TT23 sTTStsTT4i TTS? t On line terminals 


CONSONL TT62xTT72TT108*+TT113 


The following command places all devices on the system logically 
on line: 


CONSONL ALL 


This command places on line every device controller and device 
unit (except CPUs) known to the system (that is, all controllers 
and devices included at system generation). If a device unit or 


device controller lacks an access path, the command marks these 
for on-line status. 


Note that placing all devices on line takes several seconds on a 
large system and that the command does not generate any error 
messages saying that a device may not be on line. 


15-23 


RSX-11M-PLUS SYSTEM RECONFIGURATION 
ONL MEM 


ONLINE MEMORY 


(Multiprocessor systems only.) The ONLINE MEMORY command adds a memory 
box to the system configuration. To place the additional memory on 
line, you must first place the appropriate memory box port controllers 


and the memory box itself logically on line. The box you specify will 
have the highest memory addresses. 


To use the additional memory, you must expand the partition structure 


with the MCR SET /TOP command (see the RSX-11M/M-PLUS MCR Operations 
Manual). 


Format 


CON>ONLINE MEMORY memory-box 


Example 
COM ONL TNE MPNORY MEO? 
This command adds the memory box MK2: to the system 
configuration. 
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SET 


SET 


The SET command changes the value of the CSR or the interrupt vector 
address for an off-line device. The values are stored in the device 
driver's data base. 


SET cannot verify the CSR or interrupt vector address that you 
specify. If you specify an incorrect CSR address, the system will not 
be able to access the device when you issue the ONLINE command for the 
device. If you specify an incorrect interrupt vector address, the 
system will send interrupts to nonexistent interrupt vectors when you 
place the device logically on line; the device cannot be accessed. 
Also, if you specify an interrupt vector that is in use, you will get 
an error when you attempt to place the controller on line. (See the 
RSX-11M-PLUS Guide to Writing an I/O Driver for descriptions of the 
CSR and vector assignment errors.) _ 


On multiprocessor systems, the SET command also activates the sanity 
timer and enables an alarm if the timer expires. 


Format 

CON>SET controller option=value 
controller 

The device controller (for example, RHA or DMA). 
option 

One of the following: 


CSR Alters the value of the controller's CSR address 
stored in the driver data base. 


VEC Alters the value of the controller's interrupt vector 
address stored in the driver data base. 


TIMER (Multiprocessor systems only.) Activates or inhibits 
the sanity timer (controller is RHx). 


ALARM (Multiprocessor systems only.) Activates or inhibits 
an alarm upon sanity timer timeout (controller is 
RHx). 


value 


If the SET option is CSR, the value must be between 160000(octal) 
and 177777(octal). Note that if you specify a CSR address of 
160000 or less, the device is "unknown" and cannot be placed on 
line. This allows you to use the CON ONLINE ALL command without 
bringing every device on line when the current hardware 
configuration differs from the generated system. For example, if 
the target system has a DMCl1 with a CSR address of 160100, but 
the generated system has a DZlli at that address, CON ONL ALL 
attempts to bring the DMCl1l on line as a DZll. Note that the 
attempt may crash the system. 


If the SET option is VEC, the value must be less than 774(octal). 
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SET (Cont.) 


On multiprocessor systems, if the SET option is TIMER or ALARM, 
the value is either ON (to activate) or OFF (to inhibit). 


Requirement 
The device must be off line and the driver must be loaded. 
Examples 
CONSSET LEA YEO HL 6G 


This command changes the interrupt vector address for the first 
line printer controller to 160(octal). 


PAH mr Ele, See eC 


This command changes the CSR address for the first line printer 
controller to 177600(octal). 
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SWI 


SWITCH 


(Multiprocessor systems only.) The SWITCH command logically inverts 
the processor association of a switched bus run; that is, it performs 
an unlink operation followed by a link operation. The command uses a 
special hardware feature of the DTO7 to guarantee that the switched 
bus is linked to the target processor after the unlink operation. 
Thus, the SWITCH command ensures that the switched bus will be 
logically connected to the desired processor. 


For example, in a three-processor system, a properly configured 
switched bus can be connected to any one of three processors. An 
UNLINK command permits any processor to then link the switched bus. 
However, the SWITCH command specifies that only a specific processor 
can link the switched bus run following the unlink operation. If CPA 
and CPB are running as a dual-processor system and CPC is a 
single-processor system, a switch from CPA to CPB occurs even if CPC 
is trying to gain control of the bus. 


CON rejects the command if a device attached to the switched bus has 
context (that is, the device is processing or allowing processing of 
1/0). 


Format 


CON>SWITCH UBx TO CPx 


UBx 
The target-switched bus run. Switched bus runs are named using 
the designation UB followed by a letter from the DIGITAL hardware 
alphabet as follows: UBE, UBF, UBH, UBJ, UBK, UBL, UBM, UBN, 
UBP, UBR, UBS, and UBT. 
CPx 
The target processor. 
Example 
CON>OFF LPA®LFO$ ' Off line Frinter and controller 
CON>OFF YZA*sYZBsYZC*sYZ0 ! Off Line terminal interfaces 
CON>OFF TT2¢sTT3isTT43sTTS: 1 Off line a1] terminals 


CON>OFF TT6%rTT7&sTT10O%8 sTT11L13 
CON>SWITCH UBE TO CPR 
CON>ONL LPA»LPOS 

CON>ONL YZAsYZBsYZC+YZD 

CONS ONL TT229TT3ieTT4isTTS3» 
CONSONL TT6%9TT7s9TTLIOs »TT11s 


Terminals assumed nat lossted in 

On Line line Frinter and controller 
On line terminal interfaces 

On line terminals 

(Vevices now connected to CFR) 


etm em me 


This command sequence logically disconnects the first switched 
bus run (UBE) from its respective processor and then logically 
connects UBE to processor B. 
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UNL 


UNLINK 
The UNLINK command disconnects a port of a switched bus run from its 
respective processor. This command reverses the effect of the LINK 
command. 
CON rejects the command if any device attached to the switched bus has 
context (that is, the device is processing or allowing processing of 
I/O). 
Format 

CON>UNLINK UBx 
UBx 

The switched bus. 
Example 


CONZUNL UBE | Terminals assumed mot Lotsed in 


This command disconnects the switched bus port of UBE from its 
respective processor. 
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15.5 SYSTEM FAULTS 


System faults cause an RSX-11M-PLUS system to stop processing an 
application properly. A fault could be a user error, a system 
software failure, an application software error, or a hardware fault. 
User errors (for example, accidentally removing a disk from the 
system) are obvious because the fault usually occurs immediately after 
the user action. System software failures usually occur when a system 
bug is encountered while you are debugging the application software. 
Application software errors are application-specific and not discussed 
in this manual. Hardware faults -- their detection, isolation, and 
recovery from -- are discussed in the remainder of this chapter. 


15.5.1 Hardware Faults 


Hardware faults can be placed in the following categories: 
e@e Media failures 
e Transient failures 
e Intermittent failures 
e Soft errors 


@ Hard errors 


The following sections describe each of these types of faults. 


15.5.1.1 Media Failures - Media failures occur when I/O operations 
fail because portions of the medium (a disk or tape) are bad. For 
both disks and tapes, when a media failure is detected, read 
operations are retried. 


Before disks are initialized, you should check them for faulty sectors 
with the BAD utility. BAD marks the bad sectors, which prevents the 


file system from using them. (See the RSX-11M/M-PLUS Utilities Manual 
for more information.) 


Occasionally, sectors on the media become bad, causing I/O operations 
to those sectors tc fail. The error logging system can be used to 
detect these failures. (See the RSX-11M/M-PLUS Error Logging Manual 
for more information.) You should probably replace faulty media if 
they have critical data recorded on them or if a large number of 
errors occur on them. 


On devices supported by DUDRV, bad blocks may be replaced by the _ Bad 
Block Replacement Control Task (RCT). See Chapter 5 for more 
information on this process. 


15.5.1.2 Transient Failures - Transient failures cannot be repeated 
and are caused by electrical factors such as static from clothing or 
carpeting. If the failure occurs on an I/O device, the I/O operation 
is retried automatically and the application software never sees the 
failure. (The Error Logger records the failure, however.) If the 
failure occurs in memory or in a central processor, the system may 
crash and have to be rebooted. 
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15.5.1.3 Intermittent Failures - Intermittent failures are caused by 
irregular conditions within the system and usually happen during 
periods of high system or device activity. The failures usually occur 
where recorded data is corrupted enough so that it cannot be read. 
The data becomes corrupted when the device on which it is recorded is 
not working properly, usually because of a temporary power shortage. 


An example of an intermittent failure is a disk device detecting a 
power failure, which causes the disk's volume valid bit to be reset. 
Dismounting and remounting the disk clears this condition and may 
allow I/O operations to proceed. 


If the sources of intermittent failures are not obvious or directly 
reproducible, try to recreate the conditions that caused the failure 
by using the I/O Exerciser (IOX). IOX simulates high system activity, 
which could cause the failure to recur. (See Chapter 4 for 
information on IOX). 


Intermittent failures that result in device errors appear in the error 
log. 


15.5.1.4 Soft Errors - Soft errors are device errors that do not 
prevent an I/O operation from completing successfully. The device 
driver retries the operation and, depending on the capabilities of the 
device, performs ECC correction or disk-head offset positioning. 


Soft errors usually indicate poor media or a misaligned device. For 
example, disk heads that are not aligned properly cause disk errors. 
These errors can be corrected by head offset positioning. 


If several soft errors occur on a device, you should find the _ source 
of the errors and correct it through field service maintenance. 


Soft errors are recorded by the Error Logger. 


15.5.1.5 Hard Errors - Hard errors are solid device failures that 
prevent a device from working properly. The errors make the device 
unusable, but they are also the easiest to diagnose and correct. 


The Error Logger records failed operations on the disks and tapes, but 
that information is usually unnecessary since the failures are 
obvious. 


You can also use IOX to test the capabilities of many peripheral 
devices to determine if they are failing. 


15.5.2 Recoverable and Nonrecoverable Errors 


Soft errors and many media errors are recoverable errors. They are 
recorded by the Error Logger but do not impact system operation. 


Hard errors and some media errors are nonrecoverable errors. They 
usually result in recurring device errors and failure of the 
application software. (The application can survive one failure on 


each device type before it will stop processing completely.) However, 
the operating system itself often survives the failure because all it 
requires to continue running is the system disk, the central 
processor(s), and memory. 
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15.6 FAULT ISOLATION 


Once the software is stable, the availability of a system depends on 
the reliability of individual devices and the time required to restore 
processing. RSX-11M-PLUS systems can, in some cases, work around 
equipment failures in individual devices; but you must eventually 
isolate a faulty device, correct the reason for the failure, and 
restore it to the system. Depending on the severity and location of 
the error, you may have to restart the application and/or the system. 


Failures often exhibit symptoms that allow you to detect a failing 
device before it can disrupt system operation. Because of this, you 
should regularly monitor the condition of all RSX-11M-PLUS peripherals 
and their ability to respond correctly to I/O requests, by 
periodically examining the error log reports on all devices and 
occasionally running IOX on infrequently used devices. The Error 
Logger gathers information concerning all types of errors as_ they 
occur and generates comprehensive error reports. IOX tests the 
validity of mass storage devices. The tests exercise combinations of 
devices under high I/O activity. 


Both the Error Logger and IOX provide error reports that contain a 
description of device fault conditions. Use the reports to determine 
whether the device should remain in operation. If the fault 
conditions are transient (see Section 15.5.1.2) and the device is 
capable of correctly performing its I/O functions, the device can 
remain in operation. However, you should closely monitor the device 
and schedule it for future maintenance as required. 


15.7 SYSTEM RECOVERY 


The procedure you use to diagnose and recover from a system fault 
depends on the primary use of your system. If it is mainly used for 
application development, then you would want to use the Error Logger 
or IOX to determine the cause of a failure to prevent future failures. 
If your system is used for process control and is running an 
application that requires enhanced availability, utilities such as the 
Executive Debugging Tool (XDT) are necessary only as much as they can 
be used to isolate and correct failed components. Your main objective 
is to bring the system back up and restart the application, with only 
limited diagnostics for future references. 


To restart the system and the application, first bring up the minimum 
system required for running RSX-11M-PLUS. Then, gradually bring 
devices on line until you have the minimum system required for running 
the application. If any of the devices are faulty, you can take them 
back out of the system and bring others on line until you have the 
required configuration. 


The method for recovering from system faults also depends on the type 
of fault. For example: 


e Transient errors could cause the system to crash, which would 
require rebootstrapping. 


@e Hard errors require the device not to be used and possibly to 
be reconfigured out of the system so that diagnostics for it 
can be run. 


e Intermittent errors, because their source is not so obvious, 
could require you to begin with a minimum configuration and 
then gradually add devices until you find the one that caused 
the error. 
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If the minimum configuration has the problem, you will have to switch 
to another one. Another possible way to recover from intermittent 
failures is to turn the error into a hard error by imposing an 
appropriate system load using IOX. By recreating the error, you can 
discover its source and, therefore, how to correct it. 


The following sections describe how to recover from different kinds of 
hardware failures. 


15.7.1 Device Unit and Controller Failures 


Most failures in an operating system result from disk, tape, or other 
such device failures: either the units themselves fail or the 
respective controller fails. 


The time needed to reconfigure around these failures depends entirely 
on the application. If the application can notify an operator of the 
failure, thus allowing the operator to remove and inspect the media, 
mount it on another drive, and reintegrate it into the system, then 
the time to reconfigure is short. If, on the other hand, the operator 
must find a way to halt the application, move the media, and restart, 
then the time to reconfigure increases. 


On RSX-11M-PLUS systems, TKTN prints a message at the console terminal 
whenever an unrecoverable hardware error occurs. For example: 


MAK TRL on Unrecaveranle Hardwere deydioese error 


These messages can alert an operator to an impending failure and allow 
time to issue the commands to remove the failing unit from the system. 


15.7.2 Processor Failures 


Although it occurs rarely in comparison with device unit and 
controller failures, a processor failure also halts system operation. 


Note that, on multiprocessor systems, a crash or trap or other failure 
Imay occur on a processor other than the faulty one. 


If a processor fails, the system usually exhibits one of the following 
symptoms: 


@e The system traps to XDT or crashes. 


e The sanity timer expires for one or more processors 
(multiprocessor systems only). 


@ The console lights on nonremote diagnostic consoles show that 
the system is halted in the Executive. 


@ The system halts with no printouts or visual indicators. 


On multiprocessor systems, regardless of the cause of a processor 
failure, the recovery technique is straightforward and direct: you 
must isolate and exclude the disabled processor and reboot the system. 
The memory configuration need not change unless you wish to perform 
stand-alone diagnostics (see Section 15.8) on the failed processor. 
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15.7.3 MK11 Memory Box Failures 


The two most common causes of memory failures are uncorrectable 
double-bit errors (parity errors) and loss of memory power. 


If a user-state task encounters an uncorrectable memory parity error, 
the system aborts the task and locks that portion of memory. The 
Fixer task (FXR) detects the parity errors and creates a distinct 
segment in the task's region using the memory in which the errors were 
detected. This segment is separate from the rest of the region and is 
not used by other tasks. FXR is completely transparent to both users 
and tasks. 


If the Executive or a system-state task encounters an uncorrectable 
parity error, the system prints the following message and then halts: 


FORE XEC PART TY ERROR STO 
Also, the sanity timers on multiprocessing systems may expire. 


Regardless of system state (user or kernel), a double-bit error causes 
the memory box hardware to light the UNCOR ERROR light(s) on the 
respective memory box port controllers. 


When an uncorrectable error halts the system, you must manually 
exclude that memory box and rebootstrap, as follows: 


1. Switch all ports of the faulty box off line. If necessary, 
use the thumbwheel switches to properly address the remaining 
memory box(es). (The thumbwheel switches are used when the 
failed box is box 0, which is the boot box, or when you want 
to disable a memory box by changing the starting addresses of 
the remaining boxes.) 


2. Halt the processor, initialize it, and rebootstrap the 
system. 


When loss of power causes the memory failure, the system halts. The 
system exhibits one or more of the following symptoms: 


e No lights or indicators are lit. This usually indicates that 
the outside power supply has failed. 


e No MEM POWER READY lights are lit on the memory box. This 
indicates that the memory box's power supply has failed or has 
been powered down. Check the power switch on the Port A 
controller to the box. 


@ No MEM POWER READY lights are lit on one port of all memory 
boxes. This indicates that the CPU's power supply has failed 
or that the CPU has been powered down. Note that the power 
supply failure could have come through an expander box or 
through the far side of a switched bus currently switched to 
the CPU. 


In all of the above cases, if a CPU or a memory box has been switched 
off but then switched back on before the memory batteries discharge, 
the system usually recovers without rebootstrapping. Otherwise, 
follow the same two steps used when an uncorrectable error halts the 
system. 
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15.8 STAND-ALONE MAINTENANCE FOR MULTIPROCESSOR SYSTEMS 

Cn multiprocessing systems, when a device fails, it is often necessary 
to run diagnostic tasks before servicing the device. However, the 
diagnostic tasks require a processor for execution. Thus, to service 


rnost devices, you must remove a processor from the system. 


The following list gives the requirements for testing and servicing 
reripheral devices: 


1. A processor must be available to execute the diagnostics for 
the peripheral. 


2. Memory must de available for the diagnostics. 


3. A mechanism to load the diagnostic task into memory must be 
available. 


The processor that executes the diagnostics must be connected to the 


UNIBUS on which tte device to ve tested resides. This implies that 
other peripherals on that bus run will not be available to the 
remainder of the system. Therefore, when determining the initial 
system configuration, you must ensure that duplicate devices are 
located on distinct bus) runs. If the device to be tested is ona 
Switched bus run, the switched bus can be connected to any processor 


to which it has access. 


To make memory available for diagnostic tasks, the usual procedure is 
to logically remove a memory box from the running system and use the 
box for diagnostics only. This memory box is then switched manually 
so that the processor to be used for diagnostics views the box with a 
starting address of 0. : 


For loading a diagnostic into memory, the RSX-1L1IM-PLUS multiprocessor 
system provides the Diagnostic Loader task (DLD). DLD loads a 
diagnostic program into a partition in the memory box of the 
diagnostic processor (tne processor to whicl the failed device is 
attached). Diagnostic programs are system image files that you use to 
test the failed devices. The partition is created and specified by 
you and is mapped by Program Logical Address Space (PLAS) directives. 
By default, DLD clears the partition to the end after loading the 
program. The diagnostic is then run stand alone. 


he steps for using DLD are as foilows: 


1. Use FLX to transfer the diagnostic program from the 
diagnostic tape or disk to a Files-1ll device attached to the 
diagnostic processor. (See the RSX-11M/M-PLUS Utilities 


Manual for information on FLX.) Because the tape or disk is 
in DOS-11 format, use the FLX Image Mode switch (/IM) to 
convert the file (the diagnostic program) to Files-1ll format. 
The file is in formatted binary format and has a file type of 
-BIC. or .BIN. (Note that binary formatted files are not 
pat.chable.) 


2. Reconfigure your system so that you have a system with two 
CPUs and two memory boxes (each box has 256K words of 
memory). The configuration would be as follows: 


BOX O PORT A ONLINE, START=000 
PORT B OFFLINE 


BOX 1 PORT A OFFLINE 
PORT B ONLINE, START=000 


LIST Off line botn sides. 
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Bootstrap RSX-11M-PLUS on CPA. 
Set BOX O PORT A to ONLINE, START=010 


Bring Box 1 on line. This memory box will contain the 
diagnostic partition. For example: 


CONONL MKEyMK2¢ 


Use the CON DISPLAY command to find out the base address) and 
size of the memory box. For example: 


CONS DISF FULL ATT FOR MK2% 


The base address of the partition will be the base address of 
the diagnostic program. 


Create the diagnostic partition in the memory box by using 
the command SET /PAR and specifying type DIAG. This 
partition will be devoted to diagnostic functions and should 
begin at the location in memory that the diagnostic processor 
will see as location O or the bottom of memory. For example: 


“SET /FAR=JIMK$ 20000317773 DIAG 


This command creates a partition named JIMK with a base 
address of 2000000 and consisting of 1777(decimal) 32-word 
blocks. The other processors see the memory box used _ for 
diagnostics as starting at location 2000000, but the 
processor running the diagnostic will see the box as starting 
at location O. 


Other partition types used with the SET /PAR command ensure 
that the requested memory is within the system image area 
(less than $SYSIZ), but DIAG ensures only that the memory 
physically exists. For the other processor to run 
concurrently with the diagnostic processor, the partition 
must be larger than S$SYSIZ. 


Use DLD to convert the binary formatted file into a bootable 
system image file (patchable with ZAP; see the RSX-11M/M-PLUS 
Utilites Manual) and then to load it into the partition. The 
DLD command line has the following format: 


Format 
DLD>[partition]{/HE]=filename[ .typ][/qualifier] 

partition 
The partition created in the diagnostic processor's 
memory box into which the diagnostic program will be 
loaded. You must specify a partition name if you do not 
use the /NL switch (see below). DLD produces a 
"partition not found" error message otherwise. If you 
specify both a partition name and the /NL switch, the 
Switch overrides the name. 

/HE 
Provides a brief description of DLD's use and format. 


typ 


The file type for the diagnostic program. The file type 
can be .BIC, .BIN, or .SYS. 
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If the file type is .BIC or .BIN, DLD converts the file 
into a system image file. If you specify either file 
type, but DLD cannot find the file, it searches for the 
other file type before giving up. If you do not specify 
any file type, DLD first looks for a file with the .BIC 
file type and then for one with the .BIN file type. 


If the file type is .SYS, DLD does not have to convert 
the file; it is ready to be loaded into the memory box. 


/qualifier 
One of the following: 


/NL Inhibits loading of the diagnostic program 
(DLD only creates the system image file). 


/NC Inhibits clearing (zeroing) of any remaining 
memory in the partition after the diagnostic 
program has been loaded. The default is to 
clear the remaining memory. 


/OFF:n Offsets the starting location of the load by 
n times 32(decimal) words. The area between 
the beginning of the partition and the 
beginning of the diagnostic is untouched. 


/LI Lists information about the partition and 
the file: the partition name (if you have 
specified one), the base and size of the 
partition, and the new name of the system 
image file (if converted). 


Specifying this switch gives you the 
transfer address (usually 200 or 1000) of 


the diagnostic program. The transfer 
address is needed to initiate the 
diagnostic. 

/LW Accounts for the DOS-11 link word that may 


exist in bytes 0 and 1 of every input block. 
Example 


Dit JIMKR=TEST.« BIN/LI 

PARTITION NAMFS TMK 

PARTITION BASES 20000 SIZES 1777 ASP e WORD Bie K S49 
FILE NAMES TEST.SYS91 

TRANSFER ALMRESS$ 200 


This command sequence converts the binary formatted diagnostic 
file TEST.BIN into the system image file TEST.SYS. DLD also lists 
the transfer address of the file and other information about the 
file and the partition. 


DLD loads the program into a region that it creates in the 


diagnostic partition. The region is called DIAG and is the same 
size as the partition. After the program is loaded, DLD clears 
any remaining memory from the partition (unless otherwise 


specified). 


To run the diagnostic program, halt the processor (in this case, 
CPB), toggle in the transfer address of the program (from using 
the /LI switch), and then push the START button to begin the 
diagnostics. 
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ll. Use the following MCR command line to remove the diagnostic 
partition from the memory box: 


SREAAVE ULAGZREG 


15.9 ERROR MESSAGES 


The CON and HRC error messages consist of one or more lines of 
information in the following format: 


CON -- error message 
(detail of error message) 


The first line is the general error message. The second and any 
succeeding lines define the error message. 


In addition to the description, the error messages may include 
Directive Status Word error codes and I/O error. codes. For 
explanations of these codes, refer to the RSX-11M/M-PLUS and and 
Micro/RSX I/O Operations Reference Manual. 


A list of the CON and HRC error messages and a brief explanation of 
each follows. 


15.9.1 CON Error Messages 
CON -- Bad indirect command file specification 


Explanation: The name of an indirect command file (@filename) 
was specified with incorrect syntax. 


CON -- Command execution error 
Explanation: CON cannot process the specified command 
line. (More specific information is also given.) 

CON -- Command intent inconsistent with device state 


Explanation: An attempt was made to place on line a device that 
is in the marked for off-line state. 


CON -- Command list is empty. Nothing to print 


Explanation: The CON LIST command was issued when CON's internal 
buffer was empty. 


CON -- Command syntax error 


Explanation: The command line does not conform to command syntax 
rules. 


The command is displayed with a question mark (?) following the 
last recognized keyword or parameter typed by the user. Check 
the command description for correct format and reenter’ the 
command line. 


CON -- CONFIGURE Version nnn 


Explanation: This message is returned by the CON IDENT command. 
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-- CON is unable to do an extend task operation to obtain pool for 
a read of the system configuration. Please ensure that a 
checkpoint file has been allocated and reissue the CON command 
Explanation: Self-explanatory. 

-- File open error/FILE=filename/No such file 
Explanation: An invalid file specification was used with the 
LIST command. Check the device name and UFD and reenter the 
command line. 

-- HRC has timed out during initialization 
Explanation: This message could indicate an error in the I/O 
data structure. Please verify that your device data structures 
are correct. 

-- HRC version nnn 
Explanation: This message is returned by the CON IDENT command. 


-- Illegal command 


Explanation: The command is not a valid CON command or a= valid 
command was used illegally. 


-- Illegal keyword 


Explanation: The keyword is not valid for the specified CON 
command or a valid keyword was used illegally. 


-- Initialization error 
Explanation: CON was unable to properly initialize itself or its 
links with the RD: driver and the HRC... task. Verify that the 


driver is loaded and that HRC... is installed. 


-- Initialization request of HRC... has failed. Please ensure that 
HRC... is installed. 


Explanation: CON is unable to start HRC running. 


-- Input error on input command file 
FILE=filename 


Explanation: The file you have specified exists, but CON could 
not read it. 


-- Internal consistency error 


Explanation: An error internal to either CON or HRC has 
occurred. This is most often an internal addressing trap or a 
malfunctioning driver. Submit a Software Performance’ Report 
(SPR) if the problem seems to be with DIGITAL-standard software. 


-- Internal core pool exhausted 
Explanation: CON has run out of internal pool space or was 
invoked without checkpoint space first being allocated. If out 


of pool space, check the /MAXEXT setting. (See the description 
of the SET command in the RSX-11M/M-PLUS MCR Operations Manual.) 
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CON -- Maximum indirect command file depth exceeded 


Explanation: You have specified that CON use an indirect command 
file that exceeds CON's maximum nesting depth of three. 


CON -- No device name matches select string 


Explanation: You have specified with the DISPLAY command a 
logical device name that does not exist in the system. 


CON -- No HRC version information available 


Explanation: This message is returned by the CON IDENT command 
if HRC is not installed. 


CON -- No reconfiguration driver is available 
Output to HRC is suppressed 


Explanation: The reconfiguration driver (RD:) is not loaded in 
the system. 


CON -- Open error on input command file 
FILE=filename 


Explanation: The input file you have specified does not exist. 


CON -- Unable to assign command LUN 
Explanation: CON was unable to assign its command input LUN to 
Tl? 

CON -- Unknown command error 
Explanation: For undetermined reasons, CON cannot read _ the 
command. 

CON -- Unknown device or invalid device specification 


Explanation: The device specified for a command other than the 

DISPLAY command is not known to the system. Consult the system 

configuration for the proper name of the target device. 
CON -- You must be privileged to modify the system configuration 


Explanation: The command specified in the command line must be 
issued from a privileged terminal. 


15.9.2 HRC Error Messages 
The following messages are related to HRC but also come from CON. 
Attempt to quiet unit for controller failed 
Explanation: When a controller with units on line is taken off 
line, the on-line units are quieted and set to the marked for 


on-line state. HRC attempts to access the unit when it does not 
have context and can be taken off line. HRC makes 1000(decimal) 


attempts to quiet the device. If the device has not been 
successfully accessed after the 1000 attempts, CON displays this 
message. 
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Attribute format error 
Explanation: HRC received a read or write attributes QIO in 
which the desired attributes were either incorrectly specified or 
inappropriate for the specified device. 


CSR for controller not present in 1/0 page 


Explanation: An attempt was made to bring on line a_ controller 
that does not exist in the current hardware configuration. 


Device already linked 


Explanation: A LINK command was issued for a bus run that is 
already linked to a CPU. 


Device not linked 


Explanation: An UNLINK command was issued for a bus run that is 
not currently linked to a CPU. 


Device is unknown in this configuration 
Explanation: HRC has received a request to bring on line a 
device that is unknown because it had been previously assigned a 
CSR address of 160000 or less. 

Executive or driver status change error 
Explanation: During a controller on-line or off-line operation, 
either the executive controller status change routines 
(SONKRB/SOFKRB) or the driver's controller status change routine 
(xxKRB) were unable to change the state of the controller. 


HRC... can't take box offline. Not last box in memory 


Explanation: An attempt was made to take off line a memory box 


that is not at the end of the current physical memory 
configuration. 
HRC... can't take box offline. Partition overmaps box 


Explanation: An attempt was made to take a memory box off line, 
but the memory is currently in use for a partition. The 
partition must either be removed with SET /NOPAR or reduced in 
size with SET /TOP (see the RSX-11M/M-PLUS MCR Operations 
Manual). ioe 


HRC... detected I/O data base consistency error 
Explanation: During the course of taking a device off line, HRC 
detected an error in the structure of the system device data 
base. 

HRC... internal addressing error 
Explanation: An odd address trap (or other software trap) has 


occurred within HRC. This may be due to a bug in HRC or an 
inconsistency in the system's I/O data base. 
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HRC... internal tables insufficient for this system 


Explanation: HRC creates a list of units on the stack when 
taking a controller off line. This message is produced if HRC 
encounters a controller with too many units to create a list. 
The maximum number of units for each controller is defined by the 
symbol .MXCTL in HRPRE and is currently set to 256(decimal). 


HRC... invalid device specification 


Explanation: HRC received a request to bring memory on line, but 
the specified device was not a memory box. 


HRC... request format error 
Explanation: HRC received a QIO in which the format of the 
parameters was incorrect. If the issuing task for the request 
was CON, this error implies a software fault. 

HRC... unable to access device to size drive 
Explanation: When certain types of device units are brought on 
line, HRC must "size" the drive (for example, to determine if a 
DB:-type device is an RPO5 or an RPO6). This message is issued 
if the sizing process fails for any reason (for example, the 
drive is not powered up when the CON ONL command is issued). 

HRC... unknown error from online/offline call 
Explanation: HRC received from the driver on-line/off-line call 
an unsuccessful status that is not one of the normally expected 
return codes. 


Invalid device descriptor 


Explanation: HRC received a request to take a port off line, but 
the port description was invalid. 


Memory box parameter error 
Explanation: An attempt has been made to bring on line a set of 
memory boxes whose current physical configuration does not allow 
the specified command to be executed. 

Offline controller failure 
Explanation: HRC attempted to take a controller off line, but 
the controller did not properly change state. However, no 
explicit error was recognized. 

Offline unit failure 
Explanation: HRC attempted to take a unit off line, but the unit 
did not properly change state. However, no explicit error was 
recognized. 

Parameter error 
Explanation: HRC received a request to link a bus run, but’ the 


device specified was not a bus switch. If the requesting task 
was CON, this probably implies a software fault. 
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Syntax error 


Explanation: HRC received a command to link a bus run to a 
device that is not a CPU. 


Timeout on unit quieting operation 
Explanation: HRC was unsuccessful in attempting to "catch" a 
unit in its quiet state to take it off line after 1000(decimal) 
attempts. 

Unable to access bus run 
Explanation: HRC was unable to create or remove the vectors for 
a device because the device's bus run was inaccessible. Because 
HRC checks bus run status and uses the marked for on-line state 
for devices on off-line bus runs, this message probably implies a 
software fault. 

Unable to switch unit from the current controller 


Explanation: This error is displayed for two reasons: 


1. HRC attempted to take off line the controller for a port to 
which the bus switch is currently switched. 


2. HRC attempted to take off line a controller (with units) 
whose access path cannot be changed. 


Unable to take unit with context offline 


Explanation: An attempt was made to take one of the following 
units off line: 


e A mounted Files-1l device 

@ An attached device 

@e A logged-in terminal 

@e A bus switch whose bus run is currently linked 


@® A memory box unit whose memory is currently on line 
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RSX-11M-PLUS I/O QUEUE OPTIMIZATION 


I/O Queue Optimization is used to improve the throughput of the disk 
subsystem used in your RSX-11M-PLUS-~ system. Disk throughput is 
improved by making the most effective use of the list of I/O requests 
in the queue for a particular disk device. The I/O queue for the 
device is scanned by I/O Queue Optimization and after each request is 
examined, the best request is dequeued and passed to the I/O driver 
for processing. How Queue Optimization determines which I/O request 
is best, depends on which method of I/O Queue Optimization is used. 
There are three methods of I/O Queue Optimization available (you can 
also choose not to have I/O Queue Optimization): 


l. Nearest Cylinder 
2. Elevator 
3. Cylinder Scan 


The method that serves you best depends on your processing 
environment. All three methods attempt to minimize head-seek time, 
which decreases the seek-time component of the file service time. 


Because I/O Queue Optimization works by optimizing requests in the 
queue, optimization happens only when I/O requests are present in the 
queue. If the system loading is such that there are few, if any, 
requests in the queue, little optimization is achieved. 


Without I/O Queue Optimization, the operating system groups the 1/0 
requests in the queue, by priority, on a first-in/first-out basis. 
The highest priority requests appear first in the queue and are 
processed in sequence. With I/O Queue Optimization, the I/O requests 
within priority groups are examined and the request having the 
appropriate disk address is chosen as the next I/O operation. The 
highest. priority requests are still serviced first; however, 
throughput is increased by advantageous reordering of requests within 
priority. 


In some cases, I/O Queue Optimization may provide smoother disk 
operation by reducing erratic head movement. 


16.1 INITIATING OPTIMIZATION 


The MCR SET /OPT command is used to initiate I/O Queue Optimization. 
The parameters in this command are used to specify the disk device, 
the method of optimization, and a fairness count limit for passed over 
I/O requests. These parameters are explained in detail in following 
paragraphs. 
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The SET command is only for privileged users. Nonprivileged users can 
use this command only to display the optimization status of devices in 
the system. 
Format: 

SET /[NO]JOPT [=ddn:opttype:fairnesscount. ] 
Parameters 


ddn 


The disk device requiring optimization: 


DBn RP04,RP05,RP06 pack disks 

DRn RM02,RM03,RM05,RM80,RP07 pack disks 

DMn RKO6 and RKO7 cartridge disks 

DLn RLO1 and RLO2 cartridge disks 
opttype 


The type of optimization needed: 


NEAR [EST] Initiates Nearest Cylinder method; next request 
picked is the closest to current request 


ELEV [ATOR] Initiates Elevator method; requests are processed 
first in one direction along the disk and then in 
the reverse direction 

CSCAN Initiates Cylinder Scan method; requests are 
processed in only one direction along the disk 
(lowest to highest) 

The default is NEAREST. 


fairnesscount 


A limit on the number of times the most unsatisfactory I/0 
request is passed over (see Section 16.2.1). 


The default is 10. 


16.1.1 Displaying Optimization Status 
You can display the optimization status for all devices in the system 
that are currently using I/0 Queue Optimization by entering the 
following: 
SSET /ORFT 
This displays status in the following form: 
OPT=ddn:opttype:fairnesscount 
For example: 
OF T=NBOINEARL LTO. 


OPTSDBLIELEVIS. 
OF T= NBOSCSCANTS. 
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You can also display which devices are not using I/O Queue 
Optimization by entering: 


SSET /H00FT 
This displays status in the form: 
NOOPT=ddn: . 
For example: 
ACE Tos tie dg 


Nonprivileged as well as privileged users can display status. 


16.2 SELECTING THE TYPE OF OPTIMIZATION 


Selecting the correct optimization method is dependent upon the I/O 
processing environment in which your application is running, the 
physical location of data on the disk drive, and how often tasks 
access certain data areas. 


A general guideline is to try the default first. (This initiates the 
Nearest Cylinder method with a fairness count limit of 10.) Then 
compare the difference in throughput by timing the application run 
time against a suitable clock. For a closer look at disk activity and 
throughput, use Resource Accounting (see Chapter 17). Resource 
Accounting provides this data under the heading DEVICE STATISTICS in 
the output from the Resource Accounting transaction file. 


The default (NEAREST, and a fairness count of 10) is an average 
setting and, in most cases, should improve I/O throughput. As you 
become more familiar with the I/O load and data organization on the 
disk in your application, you can make adjustments by changing the 
fairness count limit or by using one of the other methods of I/O Queue 
Optimization (see the sections following). 


16.2.1 Adjusting the Fairness Count Limit 


When using I/O Queue Optimization, you should watch for increased 


waiting time. I/O requests to some data areas may have slower than 
normal access times, because Optimization categorizes them as 
unsatisfactory. When this happens, Optimization passes over these 


requests for a better choice, keeping the unsatisfactory requests in 
the queue longer. This may cause a decrease in performance for some 
tasks even though overall system performance has improved. 


To counteract increased waiting time and acquire a better balance, you 
can adjust the fairness count limit. This places a limit on how many 
times an I/O request can be passed over. Optimization increments’ the 
fairness count for the first I/O request in the queue whenever that 
request in the queue is passed over. When the fairness count for an 
I/O request reaches the limit indicated with the SET command, the 
request is Gequeued and the fairness count is cleared. 


Decreasing the fairness count limit reduces waiting time but decreases 
the overall throughput initially gained with the higher count. If you 
find you must decrease the fairness count limit, try another 
optimization method. It may be more applicable to your situation. 
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16.2.2 Nearest Cylinder Method 


The Nearest Cylinder optimization method processes the I/O request 
that is closest to the current cylinder. In general, this method is 
effective for both long and short I/O queues. There may be an 
increase in waiting time, however, and this may be unacceptable in an 
interactive environment. To remedy this, reduce the fairness count 
limit (which reduces the throughput) or try one of the other 
optimization methods. (The Elevator method may be the next best 
choice.) 


16.2.3 Elevator Method 


The Elevator optimization method processes I/O requests like an 
elevator. It processes requests as it moves in one direction along 
the disk until it reaches the last request in that direction. 
Elevator then changes direction and processes requests in that 
direction. This method is effective if there are many I/O requests 
outstanding. Also, waiting time tends to be less with the Elevator 
method than with the Nearest Cylinder method. 


The Elevator method favors the center of the disk. Requests are done 
as they are passed, and the center of the disk tends to be passed over 
twice as often as the periphery. Therefore, a task that has a number 


of requests located in the center of the disk tends to have faster I/O 
than a task with requests at the periphery. 


16.2.4 Cylinder Scan Method 

The Cylinder Scan optimization method operates like the Elevator 
method except the Cylinder Scan method processes I/O requests only 
while passing in one direction along the disk. The direction is from 
the lowest cylinder number to the highest cylinder number. This 
method is most effective if each task tends to do I/0 to a localized 


area on the disk. It results in a more even distribution of I/O among 
tasks. 


16.3 ERROR MESSAGES 
SET -- Privileged command 

Nonprivileged users can display status only. 
SET -~- Feature not supported 


User tried to initiate Optimization for a disk device that does 
not support Optimization. 


SET -- Device not in system 


User tried to initiate Optimization for a disk device that is not 
mounted in the system. 


SET -- Illegal keyword value 


User specified a fairness count higher than 128(decimal). 
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SET -- Invalid keyword 
User tried to use an invalid keyword. 
SET -- Device offline or privileged diagnostic 


User tried to initiate Optimization for an off-line device. 
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CHAPTER 17 


RSX-11M-PLUS RESOURCE ACCOUNTING 


17.1 INTRODUCTION 


RSX-11M-PLUS 
provides a 
gathers data 
billing of 
measuring of 


Resource Accounting is a system generation option that 
transaction file of system usage information. Accounting 
for both the user and the system. The data allows’ the 
individual users for the resources used, as well as the 
overall system usage. 


Some of the system usage information gathered by Resource Accounting 


and saved in 


User Data 


the transaction file is as follows: 


e Session identification, terminal, and account number 


e Billing stop date and time 


e CPU usage time 


e Tasks active at time of logout or crash 


@ Number of tasks run 


@e Number of directives and QIOs issued 


e Status at logout or crash 


Task Data 


e Session identification, terminal, and account number 


e Disk overlay loads 


e@e Number of times checkpointed 


e Number of times context has been loaded 


e Highest running priority 


e Task 


begin time and end time 


e CPU usage time 


@e Number of directives and QIOs issued 


e Status at logout or crash 


System 


RSX-11M-PLUS RESOURCE ACCOUNTING 


Data 

Accounting start date and time 

Accounting stop date and time (0 if system crashes) 
Shutdown code 

Transaction file ID, sequence number, and device 
Last scan date, time, and scan rate in seconds 
Total CPU time and total CPU zero intervals 
Total number of tasks executed 

Total number of logins 

Number of current users 

Number of checkpoints 

Number of Shuffler runs 

Number of directives issued 

Number of QIOs issued 


Login Data or Invalid Login Data 


User name, ID, terminal, and account number 
Login UIC, date, and time 


Illegal password 


Device Allocation, Deallocation Data, or Dismount Data 


Session ID, terminal, and account number 


Allocation or deallocation date, time, and device 


Device Mount 


Session ID, terminal, and account number 
Mount date, time, and device 

Volume label for Files-11l mounted device 
Type of mount (foreign, shared, and so on) 
Owner UIC 

Volume protection code 


Name of ACP for device 


Print Job Data 


Session ID, terminal, and account number 
Print job date and time 


Job name and page count 
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e Number of files printed, printer device, and forms number 
@ Job priority 
Card Reader Job Data 
@ Session ID, terminal, and account number 
e Batch or print job name 
@ Number of cards read 
e@e Reader device name and number 
System Time Change 
e@e Old Time 
@ New Time 
Device Usage Data 
e 1/0 counts 
@ Error counts 
® Tuning information 


There are several ways to access the system usage information 
contained in the transaction file. They are as follows: 


@ The SHOW ACCOUNTING commands (see Section 17.3): 


- SHOW ACCOUNTING/ INFORMATION displays system usage 
information about specific terminals. 


- SHOW ACCOUNTING/TRANSACTION FILE generates a formatted 
version of the transaction file. 

e A report program written by DATATRIEVE-11 (see Section 17.4) 

e User-written analysis programs (see Section 17.5) 
Resource Accounting gathers system usage information by collecting the 
data in account blocks in secondary pool and writing each account 
block as a record in the transaction file. These account blocks are 
as follows: 

@e Task Account Block (TAB) 

@e User Account Block (UAB) 

@ System Account Block (SAB) 


e Transaction account blocks 


For a description of account blocks, their structure, and how Resource 
Accounting uses them, see Section 17.6. 


The following sections describe the Resource Accounting commands. 
Parameters are separated by spaces, you may abbreviate, and you are 
prompted for missing parameters. All commands, except SHOW 
ACCOUNTING/INFORMATION, are privileged. (Slashes in SET and SHOW 
commands are optional.) 
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The Resource Accounting commands are: 


START/ ACCOUNTING 

STOP /ACCOUNTING 

SET ACCOUNTING 

SHOW ACCOUNTING/ INFORMATION 


SHOW ACCOUNTING/TRANSACTION FILE 


SHOW ACCOUNTING/DATATRIEVE 
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Starts up the Accounting 
subsystem 


Shuts down the Accounting 
subsystem 


Changes parameters in a started 
Accounting subsystem 


‘Displays Accounting information 


about a specific terminal 


Converts the transaction file 
to a readable format so it can 
be displayed on a terminal or 
put ina file 


Converts a transaction file to 
a file that is readable by 
DATATRIEVE-1ll. 
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START/ACCOUNTING 


17.2 CONTROL COMMANDS 


17.2.1 START/ACCOUNTING Command 


The START/ACCOUNTING command starts up the Accounting subsystem. The 
SYSLOG and ...ACC tasks must be installed before you issue the 
START/ACCOUNTING command. If you do not’ supply the optional 


parameters, they assume defaults. 


Format 


START/ACCOUNTING [parameter1][parametern] 
Parameter 
FILE: filespec 


This file specification is the name of the transaction file that 
Accounting creates to store the data. You can name the file with 
this parameter or accept the default, LB:[1,6JACNTRN.SYS. 


EXTEND SIZE:value 


This value is the size of the initial allocation for the 
transaction file and for each extension when it is needed. The 
value can be any reasonable amount. If there is low Accounting 
activity, a small extension size is adequate because few 
extensions are required and overhead is low. If Accounting 
activity is high, a larger extension size lowers the overhead if 
disk space is available for the larger extension. 


The default value is 10(10) blocks. 

POOL RESERVE:decimal value 
This value is the number of blocks of secondary pool that 
Accounting must leave free after each allocation. If Accounting 
cannot leave this amount free, the allocation will fail and 


prevent the swamping of secondary pool. 


The default is a quarter of the total secondary pool size. Use 
of the default is recommended. 


SYSTEM STATISTICS:yes/no 
This parameter specifies to Accounting whether or not to 
accumulate system-wide statistics. System-wide statistics are 
the contents of the accumulation fields in the System Account 
Block. These fields are as follows: 
@e B.CPU Total CPU time used 
e B.DIR Total directive count 
@e B.QIO Total QIO$ count 
e B.TAS Total task count 


The default is yes. 
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START/ACCOUNTING (Cont.) 


STATISTICS SCAN[:value] 


This value specifies a scan rave for the collection of device 
statistics. These device statistics are used mainly to measure 
seek-optimization parameters. They also provide excellent 
information on disk activity and throughput. The device 
statistics are collected either once or periodically. To 
indicate a one-time only collection, no value is specified. To 
collect statistics periodically, the value specifies the rate in 
minutes (nM) or seconds (nS). The default value is one hour if 
SYSTEM STATISTICS:YES is specified. 


If STATISTICS SCAN is specified, SYSTEM STATISTICS must be 
specified. This restriction does not apply to a one-time only 
request. If a value of 0 is specified or SYSTEM STATISTICS:NO is 
specified, this feature is turned off. The example below shows 
the type of statistics collected in a transaction file. 


SCAN_RATE:decimal value 


This value is the time interval between the periods when 
Accounting writes the SAB and active UABs to the scan file called 
LB:[1,6JSYSSCAN.TMP for protection against loss in event of a 
system crash. The value can be supplied as "nM" or "n" for n 
minutes, or "nS" for seconds. If you specify 0, no scanning is 
done; therefore, if the system crashes, the active UABs and the 
SAB are not recorded in the transaction file and the data is 
lost. 


The default value is 5 minutes. 


If Accounting finds a scan file when you start, it outputs a 
crash transaction and copies the data in the scan file to the new 
transaction file. A copy of this crash transaction, followed by 
the transaction file, is shown as the output of the SHOW 
ACCOUNTING/TRANSACTION FILE command in Section 17.3.2. 
Accounting copies all the old data before it writes the startup 
transaction and before it processes any new data. 


When you stop Accounting, the scan file is deleted. 
CRASH REASON: yes/no 


If you enter "yes" and Accounting is started after a crash that 
occurred when scanning was active, Accounting prompts you to 
enter a reason for the crash. The reason can be aS many as_ 60 
characters in length and is stored in the Crash Recovery 
Transaction Block. Accounting prompts for "reason for _ crash" 
when Accounting is restarted. If the system did not crash, no 
prompt occurs. 


If you enter "no", a prompt never occurs; the default is no. 


TASK: yes/no 


If you enter "yes," task accounting is initiated. Task 
accounting gathers data on individual tasks running in the 
system. You can run task accounting when the system is running 
at peak load times and the task accounting data can be analyzed 
on a per task basis to identify heavy resource users. 
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START/ACCOUNTING (Cont.) 


If you enter "no," task accounting is stopped. The default is 


no. 
Task accounting should only be specified when you absolutely need 
task accounting data. The reason is that task accounting 


requires substantial disk space because the transaction file can 
become quite large. 


Example 


The type of device statistics collected by Resource Accounting is 
shown in the following output from a transaction file: 


Device Statistics 


Time of Tlevice Statistics = 15-DEC-85 16327323 Tevice = [R13 
TO Count = 0. Words Transferred Count = 0. 
Soft Error Limit = &. Soft Error Count = 0, 
Hard Error Limit = 5. Hard Error Count = 0, 
Cylinder Crossed Count = 0, Current Fairness Count = 0. 
Fairness Count Limit = 10, 

Tlevice Statistics 
Time of Tlevice Statistics = JS-DGEC-85 16327323 Tevice = [IR23 
I0 Count = 13832, Words Transferred Count = 9002804, 
Soft Error Limit = @. Soft Error Count = 0, 
Hard Error Limit = 53. Hard Error Count = 0. 
Cylinder Crossed Count = 1053 Current Fairness Count = 0. 
Fairness Count Limit = 10, 

Tlevice Statistics 
Time of Tfevice Statistics = 15-DEC-85 16227324 Device = DR: 
IO Count = 48490. Words Transferred Count = 80640306. 
Soft Error Limit = 8. Soft Error Count = 0, 
Hard Error Limit = 5. Hard Error fount = 0. 
Cylinder Crossed Coumt = 313. Current Fairness Count = 7, 
Fairness Count Limit = 10, 


Some definitions are as follows: 


e 10 COUNT - The number of I/O requests. 
@ WORDS TRANSFERRED COUNT - The number of words transferred. 
@ SOFT ERROR - A recovered error. 


@ HARD ERROR - A nonrecovered error. (See the RSX-11M/M-PLUS 
Error Logging Reference Manual for more information about hard 
and soft errors. 


@ CYLINDER CROSSED COUNT - The number of cylinders crossed while 
accessing data. This data can be analyzed for I/O Queue 
Optimization purposes. 


@ FAIRNESS COUNT - A Queue Optimization parameter that indicates 


how many times an I/O request was passed over (see Chapter 
16). 
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SET ACCOUNTING 


17.2.2 SET ACCOUNTING Command 


This command allows you to change the value of parameters specified 
when Resource Accounting was started with the START/ACCOUNTING command 
or previously modified with a SET command. (A transaction is written 
containing the old value and the new.) 


x 


The following options can be changed while Resource Accounting is 
running: 


e The file that transactions are written to 
e The size of the extensions 
e@e The scan rate for the scan file 
@e The scan rate for collecting device statistics 
@ The state of task accounting (on or off) 
Format 
SET ACCOUNTING/[parameterl][parametern] 
Parameter 
FILE[: filespec] 


Changes the file that transactions are written to. Defaults to 
the current file specification, if not specified. 


EXTEND SIZE:value 


This value changes the size for each extension of the transaction 
file specified in the START/ACCOUNTING EXTEND SIZE parameter. 


STATISTICS SCAN:value 


This value changes the scan _ rate for collecting device 
statistics. A value of O stops this option. 


SCAN _RATE:value 


This value changes the scan rate for the scan file specified in 
the SCAN RATE parameter. A value of 0 stops this option. 


TASK: yes/no 


If you enter "yes," task accounting is started. 

When specified, task accounting creates task account blocks’ for 
all active tasks in the system. All data, for each task, is 
gathered starting at this time. 


If you enter "no," task accounting is stopped. 
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SET ACCOUNTING (Cont.) 


When specified, task accounting on a per task basis is terminated 
and the data for all active tasks is written to the transaction 
file. The only exception is tasks that have a CPU time limit 
specified, because the data is necessary for the time limit to be 


checked. The data for these tasks is written to the 


transaction 
file when the task exits. 
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STOP/ACCOUNTING 


17.2.3 STOP/ACCOUNTING Command 


This command shuts down the Resource Accounting subsystem. The 
parameter is provided to indicate why the shutdown is occurring and 
must be entered with the command. Accounting puts the reason _ for 


stopping into the System Account Block. 
Formats 
STOP/ACCOUNTING reason 
STOP /ACCOUNTING CLEAN_UP 
Reason 
MAINTENANCE 


You can use this reason when you stop Accounting for system 
maintenance. 


REBOOT 


You can use this reason if you must rebootstrap the system. 


SCHEDULED SHUTDOWN 


You can use this reason when the system is being shut down or 
used for other purposes where Accounting is not applicable. 


SHUTUP 


The SHUTUP program uses this reason as a default because it has 
no means of determining a shutdown reason. 


OTHER 


You can use this reason when any of the above reasons are not 
adequate. 


The STOP/ACCOUNTING CLEAN UP command has a special use. It must. be 
used if the SYSLOG task aborts or Accounting encounters a fatal error. 
This command cleans up all the data structures to allow Accounting to 
restart successfully. Accounting accepts this command only if it is 
necessary (after an Accounting failure or abort). 


When you use this command, the system assumes all Accounting data in 
memory to be invalid and deallocates the data back to secondary pool 
without writing it to the transaction file. Note that if the 
Accounting data structures are corrupted, the system may crash while 
it attempts to deallocate secondary pool. 


You can restart Accounting normally after you issue this command. 
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SHOW ACCOUNTING/INFORMATION 


17.3 SHOW COMMANDS 
17.3.1 SHOW ACCOUNTING/INFORMATION Command 
This command displays on the terminal from which the command . was 
issued the Accounting information for the specified terminal. 
Nonprivileged users can receive only their Accounting data. A 
privileged user can obtain any Accounting data. 
Format 
SHOW ACCOUNTING /INFORMATION[parameter ] 
Parameter 
TTn: 
If you specify TTn:, this command displays the Accounting data 
for the specified terminal. A privileged user has access to the 
Accounting data of any terminal on the system. A nonprivileged 


user can only get his own data. The default terminal is TI:. 


If you enter no terminal name, the Accounting data of the 
terminal issuing the command is displayed. 


CoO: 


If you specify CO:, the Accounting data of the system tasks 
running is displayed on the terminal. 


If you specify SYS, the current system totals are displayed on 
the terminal. 


TASK=taskname 


Shows Accounting data for the specified task if the system is 
Maintaining task accounting. 
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SHOW ACCOUNTING/TRANSACTION_FILE 


17.3.2 SHOW ACCOUNTING/TRANSACTION FILE Command 


The SHOW ACCOUNTING/TRANSACTION FILE command converts the transaction 


file into a readable format. It either displays this file ona 
terminal or writes it into another file. The SHOW ACCOUNTING/ 
TRANSACTION FILE command uses the current transaction file as the 
default file. (When Accounting is not running, there is no default 
file.) 
Format 


SHOW ACCOUNTING/TRANSACTION FILE[:inputfilespec] outputfilespec 
Parameter 
inputfilespec 


The input file is the transaction file to be read. If you do not 
specify an input file, the current transaction file is used. 


outputfilespec 


The output file can be either a terminal (specified as MTTn: or 
TI:) or a file of your choice. 


Notes 


UIC [126,10] on the distribution kit includes the source code for 
the SHOW ACCOUNTING/TRANSACTION FILE command to serve as an 
example for how to read the file. Note that the record size in 
the file is equal to the transaction length. The only exception 
to this is the Accounting startup transaction that only occurs 
once and is 512(10) bytes long. The startup transaction consists 
of a header only, but its size is increased to 512(10) bytes to 
force a file extension. See Section 17.6 or [126,10] ACNDF.DOC 
on the distribution kit for the format of this file. 


Example 


The output of the SHOW ACCOUNTING/TRANSACTION FILE command is a 
formatted display of the transaction file. The default file is 
the transaction file named in the START/ACCOUNTING command. This 
example of output of a SHOW ACCOUNTING/TRANSACTION FILE command 
is keyed to the following explanatory comments: 


ACCOUNTING DATA ~ CURREMT FOLE VI-THEC-OS Ph Enh IO4 


SYSTEM CRASH RECGRT 


TIME OF LAST SCAN = 7-TIFC-8% 10248317 SCAN RATE (SFC) = 200, 
RESTART TIME = 7-UFC-85 19258¢45 
REASON = @ 


Li=12 


Q 


RSX-11M-PLUS RESOURCE ACCOUNTING 


SHOW ACCOUNTING/TRANSACTION_FILE (Cont.) 


USER ~ ALPHA F 
SESSTON If = Fi143 TI: = TT40% ACCOUNT = 1. 
LOGIN UTC = C774417 LOGGED ON = 7-TEC-85 083582353 
LOGGED OFF = 00-9000-900 900290200 BILLING STOPPED = 7-DFC-85 10348317 
CFU = 4461. TASKS ACTIVE = 1. TASKS RUN = 95. 
QIOS = 4215, DIRECTIVES = 10240, 
STATUS ACT CRH 
USER ~ SYSTEM TASKS 
SESSION It) = $SY0 TI? = COS ACCOUNT = 0, 
LOGON UTC = £Or0] LOGGEU ON = 6-DEC-85 15348316 
LOGGET OFF = 90-00-00 00:00:00 EILLING STOPPER = 7-NFC-85 10248317 
CPU = 1038466. TASKS ACTIVE = 9, TASKS RUN = 4501. 
QIONS = 128967, NIRECTIVES = 447250, 
STATUS AT CRH 
TOTAL SYSTEM STATISTICS 4) 
ACCOUNTING STARTEU = 4-QEC-85 15249316 
ACCOUNTING STOFPFET = 600-900-000 0030035090 SHUTTIOWN CONE = 6 
TRANS FILE To = 1422 SEQ NUM = 1 VEVICE = DBLE 
TIME GF LAST SCAN = 7-TEC-85 102348317 SCAN RATE (SEC) = 300. 
TOTAL CRU = 4412464. ZERO CPW INTERVALS = 374445, 
TOTAL TASKS = 3236. TOTAL LOGONS = 40. 
CURRENT USERS = 27. CHECKPOINTS = 23, 
SHF RUNS = Q, QIRECTIVES = 2372564, QTQS = S54015,. 
ACCOUNTING STARTUP . 
ACCOUNTING STARTEM = 7-MEC-85 19358316 
LOGIN - BETA B 
GESSTON If = RXF1L TI3 = TT?43 ACCOUNT = 0, 
LOGON UTC = £7192] TIME = 7-EC-85 19°3582335 
LOGIN - ALPHA F 
SESSTON If = Fii2 TI3 = TTSS$ ACCOUNT = 1. 
LOGON UTC = {791119 TIME = 7-NEC-85 20705244 
DEVICE MOUNT 
SESSION Iti = F112 TI = TTSAS ACCOUNT = 1. 
TIME = 7-NEEO-85 29306337 VEVICE = TRL? VOL IU = WELCOMEBACK 
OWNER UTC = [0:01 ACF NAME =FIIACF VOL. FROT MASK = 0 
USFR - ALPHA F 
SESSTON JI = Fii2 TI? = TASS ACCOUNT = 4, 
LOGON UIC = £79111] LOGGED ON = 7-TEC-85 20205344 
LOGGEN OFF = 7-DEC-85 20206343 RILLING STOPFEN = 7-NEC-85 20306343 
CPI) = 141, TASKS ACTIVE = 0. TASKS RUN = 17. 


QIRECTIVES 472, QTQS = 144, 


li 
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SHOW ACCOUNTING/TRANSACTION_FILE (Cont.) 


LOGIN - OMEGA B 
SESSION ID = RXP3 TIS = TT373 ACCOUNT = 4, 
LOGON UIC = (77711 TIME = 7-NEC-85 20308211 


DEVICE ALLOCATION 


SESSION IB = RXP4 TI? = TT373 ACCOUNT = 4, 
TIME = 7-NEC-85 20209312. VEVICE = DLO?’ 
LOGIN - THETA tr 
SESSION ID = SPRS TI = TTSS3 ACCOUNT = 0. 
LOGON UIC = £77327) TIME = 7-TEC-85 20309314 . 
DEVICE MOUNT 
SESSION ID = RXF4 TI$ = TT373 ACCOUNT = 4, 
TIME = 7-DEC-85 20209315 NEVICE = DOs VOL In = 
OWNER UIC = £72107] ACF NAME = TSTACF VOL. PROT MASK = 0 
DEVICE UVEALLOCATION 
SESSION ID = RXF4 TI$ = TT373 ACCOUNT = 4, 
TIME = 7-NEC-85 20209215 NEVICE = DHoO3 
USER - SYSTEM TASKS 
SESSION If) = $SY0O TI: = CQ: ACCOUNT = 0, 
LOGON UIC = C00] LOGGED ON = 7-NEC-85 19358216 
LOGGED OFF = 00-000-00 00:00:00 RILLING STOPPEN = 7-DFC-85 20231332 
CFU = 1403, TASKS ACTIVE = 4. TASKS RUN = 64, 
DIRECTIVES = 2986. 
TOTAL SYSTEM STATISTICS 
ACCOUNTING STARTED = 7-TEC-85 19358316 
ACCOUNTING STOPPED = 7-NEC-85 20213221 SHUTQOWN CODE = 4 
TRANS FILE If = 205 SEQ NUM = 20 DEVICE = TRO? 
STATISTICAL SCAN RATE (SEC.) = 3400. FILE EXT. SIZE = 10, 
TIME OF LAST SCAN = 7-DEC-85 20813217 SCAN RATE (SEC) = 300, 
TOTAL CPU = 42460. ZERO CPU INTERVALS = 3043. 
TOTAL. TASKS = 243, TOTAL LOGONS = 7, 
CURRENT USERS = 1, CHECKPOINTS = 0. 
SHF RUNS = 0. DIRECTIVES = 10241. QIOS = 4944, 


1) The crash reason appears here if Accounting prompts you for a 
reason for the crash. The prompt occurs only if you answered yes 
to the CRASH REASON parameter in the START/ACCOUNTING command. 


@ To minimize loss of data, Accounting writes the SABs_ and 
currently active UABs to a temporary file every n seconds or 
minutes unless you specify a scan rate of 0 in the 
START/ACCOUNTING command. The process of writing this file is 
called a scan. When you restart Accounting, it copies any 
existing temporary file of Accounting data into the Accounting 
file now starting. If the scan rate is 0, the SABS_ are 
memory-resident until you stop Accounting or the system crashes. 


17-14 


RSX-11M-PLUS RESOURCE ACCOUNTING 
SHOW ACCOUNTING/TRANSACTION_FILE (Cont.) 


Also, the currently active UABs are memory-resident until a user 
logs out. Therefore, if a crash occurs with the scan rate at 0, 
all the SAB and current UAB data is lost. 


© The User Account Block (P. Alpha) shows a logged out date and 
time of O because the system crashed. There may or may not be a 
"status" line as the last line of the User Account’ Block. The 
status line indicates the bit setting of the status mask byte 
(B.STM) in the UAB. Three of the bits have external importance 
and cause this line to appear if they are on. These bits are as 
follows: 


ACT (BS.ACT) Indicates that the UAB was written to the 
file while still active (all activity had not 
ceased). This can happen when UABS are 
copied from the scan file, or when all the 
data structures are written out because 
Accounting has stopped. 


LGO (BS.LGO) Indicates that the user has logged off with 
tasks remaining active or with clock queue 
requests pending. 

CRH (BS.CRH) Indicates that this UAB came from the_ scan 
file and was copied into the transaction file 
when Accounting was started after a system 
crash. 

@ The TOTAL SYSTEM STATISTICS block contains the shutdown code as a 
digit in the range 0 through 5. These digits have the following 
meanings: 

O Accounting not stopped due to crash 

1 Maintenance 

2 Rebootstrap 


3 Scheduled shutdown 


4 Shutup 

5 Other 
The ZERO CPU INTERVALS field shows the possible error in the CPU 
time measurements. The error occurs because the system clock is 
usually run at 60 Hz and is slower than the context switch time 
of the Executive. Therefore, a task can sometimes execute for 


"zero" ticks, because the time needed for its execution is less 
than the resolution of the clock. Resource Accounting rounds 
each zero tick to one-half tick of CPU time and counts them. The 
ZERO CPU INTERVALS field contains the count of the number of zero 
ticks that have occurred. 
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17.4 WRITING AN ACCOUNTING REPORT PROGRAM USING DATATRIEVE-11 


The data collected in the transaction file pertains to your computing 


environment. How you interpret and analyze this data depends on your 
objectives. For instance, are you interested in billing or system 
measurement? To obtain the Accounting data you are looking for, in 


the form you want, you will most likely write your own report program. 
This program accesses the transaction file, reads the required data 
fields, and writes a report containing the Resource Accounting data 
you are interested in. 


One way to write this specialized report is to use DATATRIEVE-11; but 
before a DATATRIEVE-11 program can access the transaction file, the 
file must be converted to a DATATRIEVE-11 readable file. To convert 
the file, use the Resource Accounting SHOW ACCOUNTING/DATATRIEVE 
command (see Section 17.4.1). The format of the converted file is 
shown in LB:[126,24]JACNTRN.CMD along with an example of a simple 
report generator written in DATATRIEVE-1l. 


To obtain a report using the example report generator, you must 
perform the following: 


1. Use the SHOW ACCOUNTING command (see Section 17.4.1) to 
convert the appropriate transaction file to a file that is 
readable by DATATRIEVE-11. Name the file ACCOUNT.DAT (this 
is the name used in ACNTRN.CMD, for example purposes only). 


2. Copy the following files from the system disk to your 
directory: 


[1,2]QUERY.DIC 
[126,24 JACNTRN.CMD 


After the above files are made available, use the following command 
line to generate a report: 


7OTR @ACNTRN.CMD 


This command line calls DATATRIEVE-11 and executes the DATATRIEVE-11 
commands in the ACNTRN.CMD file. A brief description is then 
displayed on your terminal screen with a portion of the DATATRIEVE-11 
commands that make up the report generator. After this you are 
prompted with the following: 


Enter DEVICE OR FILE: 


You then enter where you want the Resource Accounting information 
displayed. The information can be displayed on a device or directed 
to a file. For example, the device could be your terminal: 


Enter DEVICE QR FILE: Tr? 


If you wanted to put the information in a file named ACT.REP, the 
response would be: 


Enter DEVICE OR FILE? ACT.REF 


While creating the report, you are prompted to respond with where’ the 
report should be displayed. These prompts appear at junctures in the 
report generating process where certain parts of the report can be 
either displayed or directed to a file. For example, the first prompt 
you receive is at a point where the STARTUP TRANSACTION part of the 
report can be displayed. The next prompt is at a point where the 
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first part of USER ACCOUNT BLOCK TRANSACTION can be § displayed. At 
each prompt, you can direct that part of the report to the same report 
file, a different report file, or to a device. 


To stop the Resource Accounting report process before it is finished, 
you must abort DTR. If this is done, you must recopy [1,2] QUERY.DIC 
back into your area before using the example Resource Accounting 
report program. 


17.4.1 SHOW ACCOUNTING/DATATRIEVE Command 


This command allows you to write your own Resource : Accounting report 
generator using DATATRIEVE-11. This command is used to convert an 
existing transaction file to a file that is readable by DATATRIEVE-11. 


Format 

SHOW ACCOUNTING/DATATRIEVE[:trnsfilespec] outfilespec 
Parameter 
trnsfilespec 


Specifies the name of an existing Resource Accounting transaction 
file. 


outfilespec 


Specifies the name of the output file where the converted 
transaction file is to reside. 


17.5 USER TASK INTERFACE FOR CREATING TRANSACTIONS 


You can define and create your own transactions and write them into 
the transaction file by using specific entry points in the Executive 
Accounting module. The task that you write must be privileged. The 
privileged task must enter the system state (by means of SSWSTK) and 
call one of the following entry points in the Executive module ACSUB: 
SQTRAN, SQTRN1, or SQTRN2. 


In general, before calling one of the three entry points, the task 
must have the address in register RO of a defined area (packet) that 
is within the task. Also, the task must supply in the packet a value 
for B.LEN and B.TYP (see Section 17.6.2). The packet contains the 
header and the information that is to be written as a transaction. 
The action taken by the ACSUB code depends on the entry point called 
by the privileged task. 


17.5.1 Calling $QTRAN 


The S$QTRAN routine automatically fills in the user-ID fields of the 
packet from those used by the TI: terminal of the calling task. In 
effect, this shows that the new transaction is coming from the _ same 
user who ran the task. 


To call this entry point, the task must have the address of the 


transaction packet in register RO. The two fields, B.LEN (containing 
the transaction length) and B.TYP (containing a transaction code from 
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128 through 255), must be filled in and contained within the packet. 
SQTRAN obtains the transaction header from the UAB of the privileged 
task, copies the header except for B.LEN and B.TYP into the _ packet, 
time-stamps the packet, and links the packet into a queue to be 
written into the transaction file by the SYSLOG task. SQTRAN does not 
alter the task's space, but copies the packet into secondary pool 
space before copying the header and queuing the packet into the SYSLOG 
queue. 


Example 17-1 is an example of the code needed to call SQTRAN. 
Example 17-1 Code That Calls SQTRAN 


-MCALL ACNDF$ 
ACNDF$ ;DEFINE ACCOUNTING SYMBOLS 


TRAN: .BLKB B.MLEN 


This area contains code that 
describes the data to be 
written into the transaction 


file. 

MOV #TRAN, RO 7;GET PACKET ADDRESS 
MOVB #BT.MOV,B.TYP(RO) ;FILL IN TYPE 

MOVB #B.MLEN,B.LEN(RO) ;FILL IN LENGTH 

CALL SSWSTK, ..... ;SWITCH TO SYSTEM STATE 


CALL SQTRAN 7;TO CALL QUEUE TRANSACTION EXEC ROUTINE 


17.5.2 Calling $QTRN1 


The SQTRN1 routine allows the user-ID fields to be obtained from a 
specified place, instead of assuming the current task. 


To call this entry point, the task must have filled the B.LEN and 
B.TYP fields within the packet and must have the address of the 
transaction packet in register RO. In addition, register Rl must 
contain an APR value that points to a UAB or TAB that contains the 
user-ID data that should be copied into this transaction. 


The intent is that the privileged task will write a transaction 
associated with another task. SQTRN1 time-stamps the packet and 
obtains the transaction header from the UAB of the other task. S$QTRN1 
then queues the packet in the SYSLOG queue to be written,into the 
transaction file. S$QTRN1 does not alter the packet within the _ task, 
but copies identifying information from the specified UAB into 
secondary pool, then copies data into the packet, and queues’ the 
packet into the SYSLOG queue. 


Example 17-2 is an example of the code needed to call $QTRNI1. 
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Example 17-2 Code That Calls $QTRNI1 


-MCALL ACNDFS$ 
ACNDF$ ;DEFINE ACCOUNTING SYMBOLS 


This example assumes that Rl contains the pointer 
to the TCB of the task for which the transaction 
is to be posted. 


TRAN: .BLKB B.MLEN ;START OF TRANSACTION 
MOV T.ACN(R1),R1 ;GET OTHER TASK'S UAB OR TAB ADDRESS 
BEQ 10$ ;IF EQ NO ACCOUNTING DATA PRESENT 
MOV #TRAN , RO ;POINT TO TRANSACTION HERE 
MOVB #BT.MOV,B.TYP(RO) ;FILL IN TRANSACTION TYPE 
MOVB #B.MLEN,B.LEN (RO) ;FILL IN TRANSACTION LENGTH 
CALL SSWSTK, ..-.. ;SWITCH TO SYSTEM STATE 


7;TO CALL EXECUTIVE ROUTINES 
CALL SQTRN1 


17.5.3 Calling $QTRN2 

The SQTRN2 routine assumes the calling task completely fills in the 
user-ID area of the transaction. The Executive queues the packet with 
no modification, except for a time stamp. 


To call this entry point, the task must have the address of the 


transaction packet in register RO. SQTRN2 does not obtain a header 


from any other source. Therefore, except for the transaction time, 
the privileged task must have completely filled in the transaction 
header and the transaction data contained within the packet. SQTRN2 
fills in the transaction time field in the transaction header area of 
the packet created by the user task and queues the complete packet to 
the SYSLOG queue to be written to the transaction file. 


Example 17-3 is an example of the code needed to call SQTRN2. 


Example 17-3 Code That Calls S$QTRN2 


-MCALL ACNDF$ 
ACNDFS$ ;DEFINE ACCOUNTING SYMBOLS 


TRAN: .BLKB B.MLEN 


This area contains the code that 
describes the header and data to 
be written into the transaction 
file. 


(continued on next 
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Example 17-3 (Cont.) Code That Calls S$QTRN2 


MOV #TRAN, RO ;POINT TO TRANSACTION 


MOVB #BT.MOV,B.TYP(RO) 7;FILL IN TRANSACTION TYPE 
MOVB #B.MLEN,B.LEN(RO) ;FILL IN TRANSACTION LENGTH 
MOV UID, B.UID(RO) ;USER SESSION ID 
MOV UID+2,B.UID+2 (RO) ;SECOND HALF 
MOV ACN,B.ACN(RO) ; ACCOUNT NUMBER 
MOV TID,B.TID(RO) ;TERMINAL ID 
CALL S$SWSTK, 10$ ;SWITCH TO SYSTEM STATE 
CALL SQTRN2 
RETURN 

7;TO USER 


10S: 


Figure 17-1 describes the privileged task interface just discussed. 
Section 17.6.2 contains a description of the header area fields. 


17.6 ACCOUNT BLOCKS 


There are two types of Resource Accounting account’ blocks: the 
memory-resident and non-memory-resident account blocks. The 
memory-resident account blocks are the Task Account Block (TAB), the 


User Account Block (UAB), and the System Account Block (SAB). The 
Task Account Block (TAB) accumulates accounting data per task and 
stays in secondary pool as long as a task is active. The User Account 
Block (UAB) for each logged-in user accumulates the Accounting data 
and stays in secondary pool as long as the user is logged on. The 
system's UAB accumulates data for tasks running on terminal CO:. The 
SAB stays in secondary pool and accumulates system accounting data as 
long as Resource Accounting is running. 


All other account blocks are non-memory-resident; that is, they are 
created and filled when any transaction occurs, copied by Accounting 
into secondary pool and immediately written into the transaction file. 
After these operations are completed, the space is deallocated back to 
secondary pool. 


All of the blocks have a header area that contains the same fields and 
offsets. In addition, the TAB, the UAB, and _ the SAB have data 
accumulation field areas following the header. All data accumulation 
fields have the same offsets. The information specific to the TAB, 
UAB, and SAB follows the accumulation areas. 


You can find the size and the description of the offsets in Section 
L765 2% The offsets are grouped logically; the header offsets are 
described in one group, the accumulation field offsets in another 
group, and so forth. The account and transaction block diagrams in 
Section 17.6.1 show how these groups fit together to make a functional 
account and transaction block. The account and transaction block 
diagrams are shown before the offset descriptions. 


Check the [126,10JACNDF.DOC file on the distribution kit for the 
correct numeric offsets if you plan to write a program that uses the 
offsets. In MACRO-1l programs, use the symbolic names defined by the 
ACNDF$ macro in [1,1JEXEMC.MLB. The names will not change even if 
their associated offsets change. 
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| CALLING $QTRAN 
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| CALLING $OTRN1 | 


INPUT 


USER TASK 


TRANSACTION 
PACKET: 


B.LEN = 
B.TYP = 


UAB or TAB 
HEADER 


CALLING $QTRN2 | 
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Figure 17-1 
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CALLS $QTRAN. 
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IN B.LEN, B.TYP, 
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DATA. HEADER IS 


FROM USER TASK 
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DATA WITHIN 
PACKET. 
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Account and Transaction Block Diagrams 
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Task Account Block 
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User Account Block 
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26 


32 


36 
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134 
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140 


162 


DEC 


40 


46 


50 
52 
34 


56 
58 


62 


66 
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74 


80 


82 
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36 


92 
94 


96 


114 


B.LNK 
B.TYP B.LEN 


B.ACN 
B.TID 


RESERVED 


B.BEG 
B.CPUL 
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B.CKP 
B.SHF 
B.RND 


B.FID 


B.DVNM 
B.UNIT 
B.EXTS 


B.LSCN 


B.SCNR 
B.DSCN 


RESERVED 
(18. bytes) 


B.SLEN 
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System Account Block 
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22 


DEC 


ZK-596-81 


Accounting Startup Transaction Block 


OCT 


12 


16 


20 
22 


30 
32 


126 


DEC 


24 
26 


86 


B.LNK 


B.TYP B.LEN 


B.TIM 


B.UID 


B.ACN 
B.TID 


B.CTLS 


B.CSRT 


B.CRSN 


; l (60. bytes) | | 


B.CLEN=-. 
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Crash Recovery Transaction Block 
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Set Accounting Transaction Block 
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12 


16 


20 
22 


40 


46 
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10 
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16 
18 


32 


38 


44 


B.INAM 


(14. bytes) 
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Invalid Login Transaction Block 


OCT 


26 


DEC 


B.LNK 
B.TYP 


B.TIM 


B.LEN 


B.UID 


B.ACN 
B.TID 
B.DNAM 


B.DUNT 


UNUSED 


B.DLEN - - 
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OCT DEC 
0 0 
2 2 
4 4 
12 10 
16 14 
20 16 
22 18 
24 20 
26 22 
Deallocate 
OCT DEC 
0 0 
2 2 
4 4 
12 10 
16 14 
20 16 
22 18 
24 20 
26 22 
42 34 
44 36 
46 38 
50 40 
54 44 


B.LNK 
B.TYP B.LEN 


B.TIM 


B.UID 


B.DLEN=-. 
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Device Transaction Block 


B.LNK 
B.TYP B.LEN 


B.TIM 


B.UID 


B.DLBL 


B.MLEN 
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Mount Device Transaction Block 
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OCT DEC 
0 0 B.LNK 
2 2 B.TYP B.LEN 
4 4 
B.TIM 

1 
ie : B.UID 
16 14 B.ACN 
20 16 B.TID 
22 18 B.DNAM 
24 20 B.DUNT UNUSED 
26 22 B.DLEN==. 
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Dismount Device Transaction Block 


OCT DEC 
0 0 
2 
4 
12 10 
16 14 
20 16 
22 18 
30 24 
36 30 B.TMLN=-=. 


ZK-604-82 


System Time Change Transaction Block 
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OCT DEC 

0 0 B.LNK 
2 2 B.TYP B.LEN 
4 4 

12 10 

16 14 

20 16 

22 18 

30 24 

32 26 

34 28 

36 30 

40 32 

At 33 B.PLEN 
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Print Despooler Transaction Block 


OCT DEC 
0 0 
2 
4 
12 10 
16 14 
20 16 
22 18 
24 20 
B.LNAM 
| (15. bytes) | 
43 35 B.LLEN 
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Login Transaction Block 
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OCT DEC 
0 0 
2 2 
4 4 
12 10 
16 14 
20 16 
22 18 
30 24 
32 26 
34 28 
36 30 


ZK-607-82 


Card Reader Spooling Transaction Block 


OCT DEC 
0 0 B.LNK 
2 2 B.TYP B.LEN 
4 4 
B.TIM 
12 10 
B.UID 
16 14 B.ACN 
20 16 B.TID 
22 18 
X.NAME 
26 22 
X.1OC 
32 26 X.ERHL X.ERSL 
34 28 X.ERSC X.ERHC 
36 30 
X.WCNT 
42 
i X.CYLC 
46 38 X.CCYL 
50 40 X.FCUR X.FLIM 
52 42 X.DNAM 
54 44 X.UNIT UNUSED 
56 46 X.LGTH == 


ZK-902-82 


Device Statistics Block 
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17.6.2 Account and Transaction Block Offset Definitions 


The header area fields precede the accumulation fields for the TAB, 


UAB, and SAB. The header area fields also precede each transaction 
block. 


The header provides user identification by two fields (B.UID and 
B.ACN) that appear in every transaction. These fields are the unique 
session identification and the account number. The unique session 
identification is two words long. The first word, the session 
identification, is three RAD50 characters supplied by the user when he 
creates the system account by using the ACNT program. The second word 
is a unique number assigned by the system at login. Thus, it is 
possible to match every transaction with the login session that 
produced it. The account number field is a binary word (entered 
through ACNT) that is copied into every transaction. Resource 
Accounting does not use either of these fields, except to ensure that 
they appear in every transaction. 


Header Area Fields 


Size or 
Offset Value Definition 
Start of header area: 
B.LNK:: -BLKW 1 Link to next in SYSLOG queue 
B.TYP:: -BLKB 1 Transaction type: 
000 through 127 - reserved for DIGITAL 
use 
128 through 255 - reserved for customer 
use 
BT .SAB==1 System Account Block (SAB) 
BT . UAB== User Account Block (UAB) 
BT. TAB== Task Account Block (TAB) 
BT.SS==11 Accounting startup transaction 
BT. INV==12 Invalid login transaction 
BT. TIM==13 System time change transaction 
BT.ALL==14 Allocate device transaction 
BT .DEA==15 Deallocate device transaction 
BT .MOU==16 Mount device transaction 
BT. DMO==17 Dismount device transaction 
BT .PRT==20 Print despooler transaction 
Reserved 
Reserved 
BT . LOG==23 Login transaction 
BT .CRH==24 Crash recovery transaction 
BT .DST==25 Device Statistics (UCB Extension) 
BT .RTP==26 Reset Transaction Parameters 
BT. INP==27 Card Reader Spooling Transaction 
B.LEN:: -BLKB 1 Transaction length in bytes 
B.TIM:: -BLKW 3 Ending time of transaction (supplied by 
SQTRAN, SQTRN1, $QTRN2) 
B.HID==. Start of header identification area 
B.UID:: -BLKW 2 Unique session identification 


First word - RAD50 
Second word - binary 
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- BLKW 
-BLKB 


- BLKB 


B.HEND==. 


B.CPU:: 
B.DIR::; 
B.QIO:: 
B.TAS:: 


B.BEG:: 
B.CPUL: 


B.PNT:: 


B.STM:: 


Note: 


B.USE:: 
B.ACT:: 
B.UUIC: 
B.UCB:: 
B.LGO:: 
B.ULNK: 
B.RNA:: 


1 
1 


1 


Account number 

ASCII terminal type: V - virtual, 
T - real, B - batch, C - console 
Unit number 

End of header identification area 


Accumulation Fields for User Account Block, Task Account 
ck, and System Account Block 


Blo 


- BLKW 
- BLKW 
- BLKW 
- BLKW 
- BLKW 
- BLKW 
3 - BLKW 


- BLKW 


- BLKB 
BS .ACT 
BS.CRH 
BS . LGO 


NWWNHN DNDN 


a 


1 
==200 
==100 
==40 


BS .CO==40 


BS.TM 


BS.SI 
BS.ZER 
BS .SCN 


==20 
==10 


Total CPU time used 
Total directive count 
Total QIO$ count 
Total task count (not used in TAB) 
Reserved 
Beginning/login time 
CPU time limit in TAB or UAB 
(not used in SAB) 
Pointer to SAB if system statistics 
to be collected. Equals 0 if no 
system statistics collection. In TAB 
this points to UAB. In UAB points to 
SAB if SYSTEM-STATISTICS:YES or zero. 
In SAB always zero. 
Status mask 
Control block active (UAB, TAB) 
Record from TMP file after crash (UAB, SAB) 
Logged off with outstanding 
activities (UAB only) 
Tasks TI: is CO: (TAB only) 
TAB exists only for time limit (TAB only) 
TABS with this bit set will not 
be written to the transaction file. 
Silent login/logout (UAB only) 
Last CPU interval was zero length (TAB, UAB) 
Transaction ready for write to scan (UAB, 
SAB) file 


User Account Block 


User Account Blocks must end on a word boundary. 


-BLKB 

- BLKW 
2 -BLKW 
- BLKW 
- BLKW 
- BLKW 
- BLKW 


ee 


WE WH HEE 


Use count 

Number of currently active tasks 

Login UIC 

Pointer to UCB 

Logout time 

Link to next User Account Block 

Location in system account file - 
(offset, VBN-hi, VBN-1lo) 

This will be inaccurate if the 
account file is changed (additions, 
deletions, sorts). 
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B.NAM:: -BLKB 14. Last name of user 

-BLKB 1 First initial of user 

.BLKB 1 Flag byte for UAB (BS.SIL etc.) 
B.LDS:: -BLKB 10 Login directory string 
B.ULEN==. User Account Block Length 


Task Account Block 


NOTE: Task Account Blocks must end on a word boundary. 


B.PRI:: -BLKB 1 Highest running priority 
B.TNAM:: -BLKW 2 Task name 
B.TCB:: -BLKW 1 TCB address 
B.TST3:: »~-BLKW 1 T.ST3 from task's TCB 

-BLKW 1 Reserved for future status bits 
B.CUIC:: -BLKW 1 Current UIC of task 
B.PUIC:: -BLKW 1 Protection UIC of task 
B.CTXT:: ~-BLKW 2 Number of context loads 
B.TCKP:: -BLKW 2 Times task has been checkpointed 
B.OVLY:: -BLKW 2 Number of disk overlay loads 
B.EXST:: -BLKW 2 Exit status and abort code l 
B.TLEN==. TAB length 


1. The abort codes are as follows: 


S.CACT=-4. Task still active 

S.CEXT=-2. Task exited normally 

S.COAD=0. Odd address and traps to 4 

S.CSGF=2. Segment fault 

S.CBPT=4. Break point or trace trap 

S.CIOT=6. IOT instruction 

S.CILI=8. Illegal or reserved instruction 

S.CEMT=10. Non-RSX EMT instruction 

S.CTRP=12. TRAP instruction 

S.CFLT=14. PDP-11/40 floating point exception 

S.CSST=16. SST abort-bad stack 

S.CAST=18. AST abort-bad stack 

S.CABO=20. Abort via directive 

S.CLRF=22. Task load request failure 

S.CCRF=24. Task checkpoint read failure 

S.IOMG=26. Task exit with outstanding I/O 

S.PRTY=28. Task memory parity error 

S.CPMD=30. Task aborted with PMD request 

S.CELV=32. TI: virtual terminal was eliminated 

S.CINS=34. Task installed in 2 different systems 

S.CAFF=36. Task aborted due to bad affinity (required by runs are 
offline or not present) 

S.CCSM=38. Bad parameters or bad stack 

S.COTL=40. Task has run over its time limit 

S.CTKN=42 Abort via directive with no TKTN message 
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B.SHDN:: 


B.UHD:: 
B.ULO:: 
B.ULT:: 
B.CKP:: 
B.SHF:: 
B.RND:: 


B.FID:: 
B.DVNM: : 
B.UNIT:: 
B.EXTS:: 
B.LSCN:: 
B.SCNR:: 
B.DSCN:: 


B.SLEN==. 
B.SSLN==. 


B.OFID: 
B.ODNM: 
B.OUNT: 
B.NFID: 
B.NDNM: 
B.NUNT: 
B.OEXS: 
B.NEXS: 
B.OSCR: 
B.NSCR: 
B.ODSC: 
B.NDSC: 


B.CTLS: 
B.CSRT: 
B.CRSN:: 
B.CLEN==. 
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-BLKB 1 


- BLKW 
- BLKW 
- BLKW 
- BLKW 
- BLKW 
- BLKW 


NONNMNEF EF 


- BLKW 
- BLKB 
-» BLKW 
- BLKW 
- BLKW 
- BLKW 
- BLKW 


RPE WEE tw 


-BLKW 9. 


System Account Block 


Accounting shutdown reason code 
1 - Maintenance 
2 - Reboot 
3 - Scheduled shutdown 
4 - Accounting shutdown by Shutup 
task 
5 - Other 
User Account Block listhead 
Number of users currently logged on 
Total number of logons 
Total number of checkpoints 
Total number of shuffler runs 
Number of CPU intervals rounded up 
to 1/2 
File-ID of transaction file 
Device of transaction file 
Unit of transaction file 
Extend size for transaction file 
Time of last scan 
Scan rate in seconds 
Device statistical scan rate in 
seconds 
Reserved 
System Account Block length 


SYSLOG Startup Transaction Block 


Transactior length 


Set Accounting Transaction Block 


- BLKW 
- BLKB 
- BLKW 
- BLKW 
- BLKB 
- BLKW 
- BLKW 
- BLKW 
- BLKW 
- BLKW 
- BLKW 
- BLKW 


Hee eee RW ED Ww 


File-ID of old transaction file 
Device of old transaction file 

Unit of old transaction file 

File-ID of new transaction file 
Device of new transaction file 

Unit of new transaction file 

Extend size for old transaction file 
Extend size for new transaction file 
Old scan rate in seconds 

New scan rate in seconds 

Old statistical scan rate 

New statistical scan rate 
Transaction length 


Crash Recovery Transaction Block 


-BLKW 3 
-BLKW 1 
-BLKB 60. 


Time of last scan before crash 
Scan rate before crash 

ASCII text explaining crash 
Transaction length 
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B.INAM: 
B.IUIC:: 
B.IPSW:: 
B. ILEN==. 


ee 


B.DNAM 
B.DUNT 
B.DLEN 
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Invalid Login Transaction Block 


-BLKB 14. 
-BLKB 6. 
-BLKB 6. 


Name from login line 

UIC from login line 
Password from login line 
Transaction length 


Device Transaction for Disk Accounting 
(ALLOCATE, DEALLOCATE, MOUNT, and DISMOUNT) 


-BLKW 1 
-BLKB 1 


ASCII device name 

Octal device unit number 
Transaction length for ALLOCATE, 
DISMOUNT, and DEALLOCATE 


The following fields only appear for MOUNT transactions 


B.DLBL:: 
B.DMST:: 
B.DUIC:: 
B.DVPR:: 
B.DACP:: 
B.MLEN==. 


B.TOLD:: 
B.TNEW:: 
B.TMLN==. 


-BLKB 
- BLKW 
- BLKW 
- BLKW 
- BLKW 
- BLKW 


NRE RO 


Unused byte 

Volume label 

Mount Status Bits 

Owner UIC 

Volume protection code 2 
Name of ACP for device 
Length of MOUNT transactions 


System Time Change Transaction Block 


-BLKB 6 
-BLKB 6 


Old time (yr, mon, day, hr, min, 
New time (yr, mon, day, hr, min, 
Transaction length 


2. The volume protection codes are as follows: 


Bits 


1 
LS 


Protection 


system 
owner 
group 
world 


The bit settings within each protection group are as follows: 


Bit 


WNHH OO 


Access denied (if bit set) 


read 
write 
create 
delete 
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Print Despooler Transaction Block 


B.PNAM:: -BLKW 3 Print job name (RAD50) 
B.PPGS:: -BLKW 1 Page count 
B.PNFI:: -BLKW 1 Number of files printed 
B.PFRM:: -BLKB 1 Form number 
B.PPRI:: -BLKB 1 Print priority 
B.PDEV:: -BLKW 1 Print device name (ASCII) 
B.PPUN:: ~-BLKB 1 Unit number of print device 
B.PLEN==. Transaction length 

Card Reader Spooling Transaction Block 
B.RNAM:: -BLKW 3 Batch or print job name 
B.RCDS:: -BLKW 1 Number of cards read 
B.RDEV:: -BLKW 1 Reader device name (ASCII) 
B.RUNT:: ~-BLKB 1 Unit number of reader device 
B.RSOP: : -BLKB 1 Submit or print (O=SUBMIT, 1=PRINT) 
B.RLEN==. Transaction length 

Login Transaction Block 

B.LUIC:: -BLKW 1 Login UIC 
B.LNAM:: -BLKB 14. User's last name; 

-BLKB 1 User's first initial 
B.LLEN==. Transaction length 


The following globals are also defined: 


B.MAXL==128. 
B.MINL==9. 


X.NAME: 
X.IOC:: 
X.ERHL: 
X.ERSL: 
X.ERSC: 
X.ERHC: 
X.WCNT: 
X.CYLC: 
X.CCYL: 
X.FCUR: 
X.-FLIM: 
X.DSKD: 
X.DNAM: 
X.UNIT: 


ee ee 08 e8 08 08 08 @¢8 @& 08 c¢ 8 


X.LGTH==. 


Maximum transaction length (words) 
Minimum transaction length (words) 


Device Statistics Block 


-BLKW 2 Drive name in RAD50 

-BLKW 2 I/O Count 

-BLKB 1 Hard error limit 

-BLKB 1 Soft error limit 

-BLKB 1 Soft error count 

-BLKB 1 Hard error count 

-BLKW 2 Words transferred count 

~-BLKW 2 Cylinders crossed count 

-BLKW 1 Current cylinder 

-BLKB 1 Current fairness count 
Fairness count limit 

-BLKB 1 Disk direction (high bit l=out) 

-BLKB 1 Device name for accounting 

~-BLKB 1 Unit number for accounting 

-BLKB 1 Unused 


Length of the UCB extension 
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17.6.3 Account Block Linkages 


SYSCM $SABPT 


+ 
Q 
192) 


4 
> 
wo 


T.ACN 


ed nc 


U.UAB 


a 
Cc 
im 
a2 
A 
ow 
a) 
2 
+ 
i 
oO 


B.PNT SYSTEM 


© Co: B.PNT 
B.UCB 
B.ULNK=0 


ZK-166-81 


Figure 17-2 Account Block Linkages 
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@ Terminal TT5:, which is indicated by the UCB, is that of the 
most recently logged-in user. The user of this terminal has 
started two tasks, which are indicated by the two Task 
Control Blocks (TCB) that contain pointers to the UCB 
(T.UCB) and each associated TAB (T.ACN). Each TAB’ then 
points to the terminal's UAB. The total usage of terminal 
TT5: is totaled in the associated UAB. 


@ ‘Terminal TT7: is that of the next most recently logged-in 
user. The user has started a task indicated by the single 
TCB, which points to a TAB which points to a UAB. The total 
usage of terminal TT7: is totaled in the associated UAB. 


© The CO: console terminal has associated with it a_ single 
TCB that indicates a system task is running. In effect, the 
system is also a user and has system usage accumulated at 
the task level in the TAB and totaled in the UAB associated 
with the CO: terminal. 


4) The SAB contains the usage totals for all the users 
including the system itself. The B.UHD pointer in the SAB 
points to the UAB of the most recently logged-in user. 
B.UHD and the B.ULNK words in each UAB are the linkages that 
are used when Accounting periodically writes the UABs to the 
scan file. 


@ The pointer to the SAB ($SABPT) is in the Executive module 
SYSCM. 


@ The pointer to the system UAB ($SYUAB) is in the Executive 
module SYSCM. 


“NOTE 


Although all active UCBs point to the appropriate 
UABs using U.UAB, this is not true for CO:. U.UAB 
does not exist for CO:, but instead is reflected by 
location SSYUAB. 


17.7 SYSTEM RESOURCES USED 


The following sections discuss the amount of system space that 
Resource Accounting uses. Secondary pool usage varies from a certain 
minimum to an amount determined by the number of logged-in users and 
event-associated transactions. 


17.7.1 Executive Space Requirements 


Accounting support, which is a SYSGEN option, takes up approximately 


532 words. Space in system pool is required for one active task and 
one open file. 


17.7.2 Secondary Pool Usage 


Each logged-in user requires two blocks (32 words per block) of 
secondary pool for the User Account Block (UAB); that is, two blocks 
for each logged-in terminal or virtual terminal. Each task running in 
the system requires two blocks for the Task Account Block (TAB), if 
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task accounting is enabled. Resource Accounting needs two blocks for 
the SAB and two blocks for the system UAB. Non-memory-resident 
events, such as device mounts, require one block for a brief period of 
time. 


17.8 RESOURCE ACCOUNTING MESSAGES 
Accounting messages are numbered from 1(10) through 79(10). However, 
not all of the numbers in this range are used. The number appears at 
the start of the Accounting message. The Accounting messages have the 
following format: 

hh:mm:ss aaaTnn nn. *aaaaaa* message... 
where: 


hh:mm:ss 


The time of the message occurrence is hh:mm:ss 


aaaTnn 


The task issuing the message and the terminal executing the task 


are displayed as aaaTnn. The first three letters of the task 
name are indicated by aaa. Tnn is the terminal number of the 
terminal executing the task. SYSLOG appears if the message 


originated from that task. 


nn. 
The message number is nn. The message number enables you to find 
a description of the message in the following list of messages. 
*aaaaaa* 


The message severity code is aaaaaa and it has four’ forms. It 
may not be present; if it is not, the message is an informational 
message. The four forms of the severity code are as follows: 


*DIAG* - Information only 

*WARN* - Possible error condition 
*ERROR* - Command did not succeed 
*FATAL* - Extreme error condition 


The following is a list of the Accounting messages: 


nn:nn:nn aaaTnn 1. Undefined message number nn. at PC aaaaaa 
Explanation: The message number is a decimal number specified by 
nn. The location is specified by the address aaaaaa. This is an 
internal Accounting error. 


User Action: Submit a Software Performance Report (SPR). 
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nmnznnz:nn aaaTnn 2. Directive error. $DSW=nnn PC is just before aaaaaa 


Explanation: The directive error code is an octal number 
specified by nnn. The PC contains an address just preceding the 
octal address aaaaaa. This message provides additional 
information to a message that will appear with it. 


User Action: Look up the directive error code in the 
RSX-11M-PLUS Mini-Reference to obtain more information. 


nn:nn:nn aaaTnn 4. FCS aaa ERROR CODE = nnn 

FILE: DBn: [??7?,???]filename.filetype;v 
Explanation: The word "I/O" or "DSW" is specified by aaa. The 
error code is specified by ‘nnn. The UIC is inaccessible and 
appears as question marks. 
User Action: Refer to the RSX-11M-PLUS Mini-Reference for an 
explanation of the error code. 


nn:nn:nn aaaTnn 5. *ERROR* Illegal filename 


Explanation: The file name specified in the START/ACCOUNTING 
command is invalid. 


User Actions: Correct the file name and reenter the command. 


nn:nn:nn aaaTnn 6. *FATAL* Can't open transaction file 


[message] 
Explanation: The transaction file could not be created for the 
reason specified in the message that follows "Can't open 


transaction file." 


User Action: Determine the cause of the error and correct it. 


nnz:nn:nn aaaTnn 7. *FATAL* Can't open transaction file (by id) 


[message] 
Explanation: After it was created, the transaction file became 
inaccessible for reason specified in the message that follows 


"Can't open transaction file (by id)." 


User Action: Issue STOP/ACCOUNTING CLEAN _UP, determine the cause 
of the error, correct it, and restart Accounting. 
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nnz:nn:nn aaaTnn 8. *FATAL* Can't write transaction file 


[message ] 


Explanation: The transaction file could not be written for the 
reason specified in the message that follows "Can't write 
transaction file." Accounting cannot recover from this’ error. 
Accounting data is lost because the file cannot be written. 


User Action: Issue STOP/ACCOUNTING CLEAN UP, determine the cause 
of the error, correct it, and restart Accounting. 


nn:nn:nn aaaTnn 9. *ERROR* Can't close transaction file 


Explanation: The transaction file could not be closed. 
Acounting cannot recover from this error. Accounting data is 
lost because the file cannot be closed. 


User Action: If possible, determine why the file cannot be 
closed. Restart Accounting for a_ short period to see if the 
error recurs. 


nn:nninn aaaTnn 10. *FATAL*® Can't init new blocks 


Explanation: The transaction file cannot be written when the 
file is being extended. Accounting cannot recover from this 
error. Accounting data is lost because the file cannot be 
written to be extended. 


User Action: Issue STOP/ACCOUNTING CLEAN _UP, determine the cause 
of the error, correct it, and restart Accounting. 


nmninn:nn aaaTnn 11. *FATAL* Can't init new blocks. I/O error = nnn 


Explanation: The transaction file cannot be written when the 
file is being extended. Accounting cannot recover from this 
error. Accounting data is lost because the file cannot’ be 
written to be extended. 


User Action: Issue STOP/ACCOUNTING CLEAN UP, determine the cause 
of the error, correct it, and restart Accounting. 


An explanation of the I/O error code can be found in either the 
RSX-11M Mini-Reference or the RSX-11M-PLUS Mini-Reference. 


nnz:nn:inn aaaTnn 12. *FATAL* Can't write attributes. I/O error = nnn 


Explanation: The transaction file cannot be written when the 
file is being extended. Accounting cannot recover from this 
error. Accounting data is lost because the file cannot be 
written to be extended. 


User Action: Issue STOP/ACCOUNTING CLEAN UP, determine the cause 
of the error, correct it, and restart Accounting. 


An explanation of the I/O error code can be found in the 
RSX-11M/M-PLUS Mini-Reference. 
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nmnz:nn:nn aaaTnn 13. *FATAL* Can't write attributes 
Explanation: The transaction file cannot be written when the 
file is being extended. Accounting cannot recover from this 
error. Accounting data is lost because the file cannot be 
written to be extended. 
User Action: Issue STOP/ACCOUNTING CLEAN _UP, determine the cause 
of the error, correct it, and restart Accounting. 


nn:nn:nn aaaTnn 14. *FATAL* Secondary pool allocation failure 


Explanation: There is insufficient secondary pool remaining to 
start Accounting. 


User Action: Use VMR (Chapter 10) to increase the secondary pool 
partition size, and rebootstrap. 
nn:nn:nn aaaTnn 15. *FATAL* Bad SYSLOG queue 


Explanation: The SYSLOG task's input is not empty during 
Accounting startup. 


User Action: Issue STOP /ACCOUNTING CLEAN UP and restart 
Accounting. 

nn:nn:nn aaaTnn 16. *ERROR* Accounting already active 
Explanation: Accounting is already active. 


User Action: None. 


nn:nn:nn aaaTnn 17. *FATAL* Error spawning SYSLOG 


[message] 


Explanation: The SYSLOG task could not be started due to the 


reason specified in the message that follows "Error spawning 
SYSLOG." 


User Action: Determine the cause of the error, correct it, and 
restart Accounting. 


nnz:nn:nn aaaTnn 18. Accounting system not started 


° 
e 


e 


[message] 
Explanation: Accounting was not started because of the reason 
specified in the message that follows "Accounting system not 
started." 


User Action: Determine the cause of the error, correct it, and 
restart Accounting. 
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nnsnn:nn aaaTnn 21. SYSLOG exit with status = n. 


[message] 


Explanation: The exit status of the SYSLOG task is represented 
by the decimal number n. See the accompanying SYSLOG message. 


User Action: Correct the problem, if there is one, and try 
again. 
nn:nn:nn aaaTnn 22. *ERROR* SYSLOG not installed 


Explanation: The SYSLOG task was not installed when 
START/ACCOUNTING was specified. 


User Action: Install SYSLOG and reissue the START/ACCOUNTING 
command. 
nn:nn:nn aaaTnn 23. *ERROR* Error bit set. Cleanup before restart. 


Explanation: Accounting had an error and cannot be restarted 
until you issue the STOP/ACCOUNTING CLEAN UP command. 


User Action: Issue the STOP/ACCOUNTING CLEAN UP command and 
restart Accounting. 
nn:nn:nn aaaTnn 25. *ERROR* Accounting did not crash 


Explanation: A STOP/ACCOUNTING CLEAN UP command was issued 
unnecessarily. 


User Action: None. 


nmn:nn:nn aaaTnn 27. *FATAL* System command handling error 
Explanation: This is a Get MCR command line directive failure. 
User Action: None. The ACC task was RUN, so no command line was 
queued. Access to this task is only legal with the specified 
Accounting commands. 


nnz:nn:nn aaaTnn 28. *ERROR* Privilege violation 


Explanation: You did not have the privilege for the specified 
operation. 


User Action: None. Nonprivileged users can see the Accounting 
data for their terminal only. 
nnz:nn:nn aaaTnn 29. *ERROR* Accounting not supported in system 


Explanation: Accounting cannot be used unless it is selected as 
an option in SYSGEN. 


User Action: Do another SYSGEN and select Accounting as an 
option. 
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nnznn:nn aaaTnn 30. *ERROR* Illegal command or parameter 
Explanation: The entered command is incorrect. 


User Action: Enter the correct command. 


nnz:nn:nn aaaTnn 31. *ERROR* Command or parameter ambiguous 


Explanation: Parameter was entered with too few letters to 
uniquely identified. 


User Action: Reenter the command with more letters in 
parameter. 
nn:nn:nn aaaTnn 32. *ERROR* Syntax error 


Explanation: The entered command is incorrect. 


User Action: Enter the correct command. 


nn:nn:nn aaaTnn 33. *ERROR* Terminal I/O error 


Explanation: A terminal I/O error occurred during a prompt or 
read to the terminal. 


User Action: Try the operation again. 


nn:nn:nn aaaTnn 34. *ERROR* Repeated or contradictory parameter 
Explanation: Illegal or duplicate parameter combination. 


User Action: Enter the correct command parameter. 


nmn:nn:nn aaaTnn 35. *ERROR* Required parameter missing 
Explanation: A parameter is missing in the command line. 


User Action: Reenter the command with the required parameter. 


nn:nn:nn aaaTnn 36. *ERROR* Value out of range 


Explanation: The value entered was either too large or 
small. 


User Action: Reenter the command with the correct value. 


nn:nnznn aaaTnn 38. *ERROR* No accounting data present 


be 


the 


too 


Explanation: The terminal specified in the SHOW ACCOUNTING/- 


INFORMATION command either does not have any Accounting data 
is not logged in. 


or 


User Action: Determine the correct terminal to use and reenter 


the command. 
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nnz:nn:nn aaaTnn 39. *ERROR* Device specification error 


Explanation: A device specification was entered incorrectly in 
the command line. 


User Action: Determine the correct device and reenter the 
command. 
nnz:nn:nn aaaTnn 40. *FATAL* No startup transaction found 

Explanation: The START/ACCOUNTING command and the SYSLOG task 
are closely related and depend on each other for correct 
operation. Any attempt to start the SYSLOG Accounting task by 
any method other than the use of START/ACCOUNTING results in this 
message. 

User Action: If START/ACCOUNTING and SYSLOG were used as 


intended and this error resulted, submit an SPR. 


nn:nn:nn aaaTnn 41. *WARN* Bad transaction length. Block(s) of secondary 
pool may be lost 


Explanation: A transaction was probably too large or too _ small 
and is probably a user-designed transaction. 


User Action: Correct the generation of the transaction. See 
B.MINL or B.MAXL in Section 17.6.2. 

nnz:nninn aaaTnn 42. *ERROR* UAB Listhead not zero on shutdown 
Explanation: Internal consistency error. 


User Action: Submit an SPR. 


nn:inn:nn aaaTnn 43. *ERROR* Transactions follow SAB 
Explanation: Internal consistency error. 


User Action: Submit an SPR. 


nnz:nn:inn aaaTnn 44. *FATAL* UAB Not found in list 
Explanation: Internal consistency error. 


User Action: Submit an SPR. 


nnznnznn aaaTnn 45. *FATAL* Exiting due to error 


Explanation: SYSLOG exited for the specified reason. The 
specified reason is in the message that appears with this one. 


User Action: Issue STOP/ACCOUNTING CLEAN UP, determine the cause 
of the error, correct it, and restart Accounting. 

nn:nnznn aaaTnn 46. *FATAL* Transaction not in secondary pool 
Explanation: Internal consistency error. 


User Action: Submit an SPR. 
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nnsnn:nn aaaTnn 47. Exiting 
Explanation: Normal SYSLOG exit due to STOP /ACCOUNTING command. 


User Action: None. 


nmn:nn:inn aaaTnn 50. Accounting not active 


Explanation: The command issued requires Accounting to be 
running. 


User Action: Issue START/ACCOUNTING and reissue the command. 


nnznn:nn aaaTnn 51. *ERROR* Accounting had a fatal error, must be 
cleaned up 


Explanation: Accounting failed. 


User Action: Issue the STOP/ACCOUNTING CLEAN UP command. 


nn:nn:nn aaaTnn 52. *ERROR* SYSLOG Not active 
Explanation: SYSLOG has unexpectedly exited. 
User Action: Issue the STOP/ACCOUNTING CLEAN _UP command and 


restart Accounting. 


nnz:nn:nn aaaTnn 53. *ERROR* Cannot write crash transaction 


[message] 
Explanation: The crash transaction could not be written to the 


new transaction file for the specified reason following "Cannot 
write crash transaction." The crash data is lost. 


User Action: None. 


nn:nn:nn aaaTnn 54. *ERROR* Error during scan file rename 


Explanation: The specified error was encountered when dealing 
with the scan file. 


User Action: Determine the cause of the problem and correct it. 


nns:snns:nn aaaTnn 55. *ERROR* On scan file PUTS 


Explanation: The specified error was encountered when dealing 
with the scan file. 


User Action: Determine the cause of the problem and correct it. 
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nn:nnz:nn aaaTnn 57. Enter reason for the crash (Maximum 60. characters) 
Explanation: This is the prompt for the user-supplied crash 
reason because "yes" was answered as the CRASH REASON parameter 
on the START/ACCOUNTING command. 


User Action: Enter a crash reason. 


nn:nn:nn aaaTnn 58. *ERROR* Terminal I/O Error 


Explanation: An I/O error occurred from the terminal during the 
input of the crash information. The crash information is lost. 


User Action: None. 


nn:nn:nn aaaTnn 60. *ERROR* I/O Error 


Explanation: The specified I/O error occurred during the SHOW 
ACCOUNTING TRANSACTION command. 


User Action: Correct the I/O condition and try the command 
again. 
nn:nn:nn aaaTnn 64. *ERROR* Illegal file name 


Explanation: There is an incorrect file specification for the 
SHOW ACCOUNTING TRANSACTION command. 


User Action: Correct the file specification and try the command 
again. 
nnsnn:nn aaaTnn 65. *ERROR* Open error 


Explanation: The specified error occurred during a file open 
procedure of the SHOW ACCOUNTING/TRANSACTION FILE command. 


User Action: Determine the cause of the error, correct it, and 
try the operation again. 
nmnz:nn:nn aaaTnn 70. *ERROR* On scan file open 


Explanation: The specified error was encountered when Accounting 
was processing the scan file. 


User Action: Determine the cause of the problem and correct it. 


nnz:nnz:nn aaaTnn 71. *ERROR* On scan file delete 


Explanation: The specified error was encountered when Accounting 
was processing the scan file. 


User Action: Determine the cause of the problem and correct it. 


17-48 


RSX-11M-PLUS RESOURCE ACCOUNTING 


nnz:nn:nn aaaTnn 72. *ERROR*® On scan file close 


Explanation: The specified error was encountered when Accounting 
was processing the scan file. 


User Action: Determine the cause of the problem and correct it. 


nn:nn:nn aaaTnn 73. *ERROR* On scan file open 


Explanation: The specified error was encountered when processing 
the scan file. 


User Action: Determine the cause of the problem and correct it. 


nn:nn:nn aaaTnn 74. *ERROR* Copying scan file to trans file 
Explanation: The specified error was encountered when processing 
the scan file. The crash information that would have appeared in 
the transaction file is lost. 


User Action: None. 


nn:nn:nn aaaTnn 75. *ERROR* On scan file close 


Explanation: The specified error was encountered when processing 
the scan file. 


User Action: Determine the cause of the problem and correct it. 


nn:nn:nn aaaTnn 76. *ERROR* On scan file delete 


Explanation: The specified error was encountered when processing 
the scan file. 


User Action: Determine the cause of the problem and correct it. 


nn:nn:nn aaaTnn 79. *ERROR* Task not in memory or not active 
Explanation: The task specified with the SHOW 
ACCOUNTING/INFORMATION TASK=taskname command was not in memory or 
was not active. Therefore, there is no task accounting date for 
this task. 


User Action: None. 
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RSX-11M-PLUS SHADOW RECORDING 


Shadow Recording (which is a system generation option) is an Executive 
feature of RSX-11M-PLUS that allows your system to back up all new 
data as it is written to a Files-1l disk. This chapter describes 
Shadow Recording, how to prepare your system for it, and how to 
control it. There is also a discussion of bad block handling and a 
list of error messages. 


Shadow Recording creates two identical sets of disks called a 
"shadowed" pair. More than one pair of disks may be shadowed, but 
shadowed disk pairs cannot overlap. The first disk of the pair, the 
primary disk, is the original disk that exists whether or not Shadow 
Recording is active. You can make any disk on your system, including 
the system disk, the primary disk of a shadowed pair. By using the 
preparatory procedure described in Section 18.1 and the START command 
described in Section 18.2, the second disk of the pair (the secondary 
disk) becomes an exact copy of the primary disk. 


The START command invokes a Shadow Recording task called SHAddn (or 
SHddnn), where ddnn is the device unit of the primary disk. This task 
is the "catchup" task that copies the primary disk to the secondary 
disk. Shadow Recording occurs while catchup is in progress. In other 
words, records are written to both the primary disk and secondary 
disk, without interfering with the catchup process. 


After you issue the START command, Shadow Recording provides a dynamic 
backup of all blocks as they are written to the primary disk. Shadow 
Recording has important uses in the following applications: 


e Duplicating important information to prevent inadvertent 
damage or loss. With Shadow Recording, critical data is 
duplicated on two disks. This redundancy prevents loss of 
data if a disk error occurs and, therefore, may provide 
quicker recovery time in critical applications. Also, 
downtime may be reduced because disk errors do not necessarily 
mean an application must be halted. 


@ Providing on-line backup to give an “instant" duplicate disk 
where later backup time or resources are unavailable. 


The Shadow Recording feature operates transparently because writing to 
and reading from the secondary disk is an Executive function. The 
Executive always writes the same data to the secondary disk that it 
writes to the primary disk when Shadow Recording is active. However, 
when a disk read occurs, the Executive reads the primary disk first. 
If a read error occurs on the primary disk, the Executive reads the 
secondary disk. The Executive displays all I/O errors occurring on a 
Shadow Recording disk pair on the operator's console. 
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Now that you are generally familiar with Shadow Recording, proceed 
first to Section 18.1 to prepare your system, and then to Section 18.2 
to learn how to control Shadow Recording, beginning with the START 
command. START is one of five commands you can use to control Shadow 
Recording. Note, however, that you can enter these commands only from 
a privileged terminal. 


If you encounter errors during any of the Shadow Recording procedures, 
refer to Sections 18.3 and 18.4. 


18.1 PREPARING YOUR SYSTEM FOR SHADOW RECORDING 


More than one pair of disks can be shadowed, but shadowed pairs cannot 
overlap. For example, if you make DBO: and DBl: a shadowed pair, 
you can make DB2: and DB3: a shadowed pair but not DBI: and DB2:. 
Additionally, the devices must be of the same type. 


Before you can use a pair of disk drives for Shadow Recording, you 
must have available two identical disk packs. The two disk packs must 
have the same bad block data. You can make the bad block data on the 
two disks functionally equivalent by following the procedures 
discussed next. 


In the following procedure, the assumption is made that you will 
shadow record the system disk. However, the procedure is valid for 
any two devices of the same type. To get ready for Shadow Recording, 
you must perform the following actions for each shadowed pair: 


1. You must select Shadow Recording as an option during system 
generation before you can run Shadow Recording. 


2. Determine which two device units you want to use for the 
shadowed pair. They must be the same type of device, for 
example, two RPO6s or two RMO2s. One of these two devices 
will be the device that will contain the primary disk that 
you want to be "shadowed." The other will contain the 
secondary disk. 


If, for example, your system has four RPO6s and you decide to 
shadow record the system device, DBO:, you can select one of 
the three remaining devices as the secondary device of the 
shadowed pair: DBl:, DB2:, or DB3:. 


3. Next, gather a set (three or more) of disks that you can use 
for Shadow Recording. There are two principles involved with 
the selection of the set of disks for Shadow Recording: 


e The disks being used for Shadow Recording must be 
logically equivalent (have the same bad blocks). To make 
the disks logically equivalent, you select one disk of the 
set as the primary disk and make its bad block descriptor 
block a logical OR of all the bad blocks in the set of 


disks. Then, when you start Shadow Recording, the 
contents of the primary disk, including the bad _ block 
information, are copied to the secondary disk. 


Subsequently, the Executive writes the same data to _ the 
secondary disk that it writes to the primary disk. 
Because the bad block information on the primary disk is 
an OR of its own bad blocks and those of the secondary 
disk, the write to the secondary disk does not occur for a 
defective block. 
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You can make the disks logically identical by making 
entries in the bad block descriptor block of the primary 
disk (see step 4). 


@ You can use another disk of the set as a spare, logically 
equivalent disk in case of disk errors. This is why you 
should have selected three or more disks for your set of 


Shadow Recording disks. Using one of these spare disks 
enables quick recovery from possible disk errors and 
decreases downtime in critical applications. Error 


recovery is discussed in Section 18.3. 


4. Before you make entries in the bad block descriptor block of 
the primary disk, run the Bad Block Utility (BAD) with the 
/LI switch on all the disks in the set of Shadow Recording 
disks. BAD locates the bad blocks and lists them on your 
terminal. This list includes the information you need to 
make the bad block descriptor block on the primary disk the 
logical OR of all the bad blocks. 


Now, you can make entries in the bad block descriptor block 
of the primary disk by using the INITVOLUME command with the 
/BAD=[MAN] keyword, as follows: 


>INI ddnn:/BAD=[MAN ] 


After you enter the INITVOLUME command, the following prompt 
is displayed: 


INI>LBN(S)= 


In response to this prompt, you can then type from the 
terminal the list of bad blocks. (The INITVOLUME command is 
described in greater detail in the RSX-11M/M-PLUS MCR 
Operations Manual.) Also, this bad block information will be 
used by subsequent INI, DSC, or BRU operations on this 
volume. The Disk Save and Compare Utility (DSC) and the 
Backup and Restore Utility (BRU) are described in the 
RSX-11M/M-PLUS Utilities Manual. 


5. Copy the data from your system disk to your primary disk. 
This disk becomes the primary disk and your new system disk 
for Shadow Recording. 


For example, if you want to shadow record your system disk, 
copy it to the primary disk. After this is done, you will 
have two system disks with identical data, but they will not 
be identical physically because of the bad block locations. 
The new system disk becomes the primary disk for shadow 
recording. 


6. Mount as foreign one of the previously selected disks on the 
secondary device. Use the following MOUNT command: 


>MOUNT ddnn:/FOR 


Now you are ready to use Shadow Recording, beginning with the START 
command (see Section 18.2). 
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18.2 CONTROLLING SHADOW RECORDING 


You can use five commands to control Shadow Recording. The commands 
allow you to start, stop, abort, or continue Shadow Recording and to 
display all device pairs that are being "shadowed." The five commands 
are: 


1. START 
2. STOP 
3. ABORT 


4. CONTINUE 

5. DISPLAY 
Note, however, that you can only enter these commands from a 
privileged terminal. You may enter these commands on one line, for 
example: 

>SHAdow START 
Or, you may enter the commands on two lines, for example: 

>SHA 


SHA>START 


The following sections describe the commands. 
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START 


18.2.1 START Command 


The START command: 


@e Verifies that the primary disk is a Files-ll device and is 
mounted 


@ Verifies that the secondary disk is mounted as a foreign 
device 


e Verifies that both the primary and secondary disks are 
identical disk types 


e Sets up the Shadow Recording data structure (UMB), which 
starts the Shadow Recording task within the Executive 


e Starts the copying of the primary disk to the secondary disk 
(catchup) 


Format 
START ddnn: TO ddxx: 
Parameters 


ddnn: 


The primary Files-ll device that is to be shadowed on the 
secondary Files-1ll device. 


adxx: 


The secondary device that is to be the shadowed copy of the 
primary device. 


The START command copies the primary disk onto any secondary disk of 
the same device type. After you make the bad block information 
identical and then use the START command, the secondary disk becomes a 
logical duplicate of the primary disk. This means that all copied 
data blocks, bad blocks, headers, directories, and so forth occupy the 


same logical locations on the secondary disk as they do on the primary 
disk. 


Both disks have equivalent logical block numbers and, in the case of 
system disks, both disks are bootable. In addition, after the START 
command is issued, the secondary disk becomes a Files-ll format disk 
because the START command makes an exact copy of the primary disk on 
the secondary disk. 


If new data is written to the primary disk after Shadow Recording is 
initiated with the START command, Shadow Recording also writes the new 
data to the secondary disk. That is, when a write occurs on the 
primary disk, it also occurs’ on the secondary disk. However, the 
secondary disk can only be read from the last portion that has been 


copied. The information about the last block copied is in the UMB 
control block. A fully redundant secondary disk does not exist until 
catchup has completed. Further action on your part is unnecessary 


unless you want to stop Shadow Recording. 
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STOP 


18.2.2 STOP Command 


The STOP command: 


@e Verifies that the primary device is part of a shadowed pair 


@e Unlinks the UMB data structure, if no outstanding I/O exists, 
thereby stopping the Executive from Shadow Recording 


@ Marks the data structure for deletion if outstanding I/O does 
exist 


Format 

STOP ddnn: 
Parameters 
ddnn: 

The device unit of the primary device. 
The STOP command prevents Shadow Recording from continuing. However, 
during catchup, the STOP command cannot stop Shadow Recording. In 
fact, if you issue the STOP command during catchup, you receive an 


error message. To stop Shadow Recording during catchup, use the ABORT 
command (see Section 18.2.3). 


The absence of outstanding I/O does not necessarily mean that all file 
activity has stopped. You must make certain that all tasks that write 
records to the shadowed pair have stopped to ensure the integrity of 
the secondary data before you issue STOP or ABORT. 
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ABORT 


18.2.3 ABORT Command 
The ABORT command: 
e Verifies that the primary disk is part of a shadowed pair 


@e Aborts catchup if it is in progress and then executes a STOP 
command 


@ Stops Shadow Recording even if catchup is in progress 


Format 
ABORT ddnn: 
Parameters 


ddnn: 


The device unit of the primary device. 
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CONTINUE 


18.2.4 CONTINUE Command 


The CONTINUE command: 


@ Assumes that the primary and secondary disks are identical 


@e Verifies that the primary disk is in Files-ll format and 
mounted properly 


e Verifies that the secondary disk is mounted foreign 
@e Verifies that both disks are identical device types 


e Sets up the Shadow Recording data structure, which starts 
Shadow Recording within the Executive 


Format 
CONTINUE ddnn: TO ddxx: 
Parameters 
ddnn: 
The device unit of the primary device. 


adxx: 


The device unit of the secondary device. 


The CONTINUE command allows you to restart Shadow Recording on the 
same two disks that you were using when the STOP command was issued. 
The CONTINUE command assumes that the two disks are physically alike, 
and it does not check the disks for equality. You must be sure that 


no writing occurred on the primary or secondary disks after you issued 
the STOP command. 
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DISPLAY 


18.2.5 DISPLAY Command 
The DISPLAY command shows all shadowed pairs. 
Format 

DISPLAY 


The shadowed device pairs are displayed in the following format: 


UMB PRIMARY SECONDARY 
Parameters 
XXXXXX ddnn: ddxx: 
XXXXXX 
The address of the UMB control block for Shadow Recording. This 


control block is in the system Executive pool space. 
ddnn: 

The device unit of the primary device. 
ddxx: 


The device unit of the secondary device. 
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18.3 BAD BLOCK HANDLING 


Except for the START command, which copies the primary disk to the 
secondary disk, the Executive writes the data from a task buffer to 
the primary disk and then writes it from the task buffer to the 
secondary disk. If write errors occur on one of the disks, you may 
not know it until the Executive attempts to read the block in error. 


To be notified of write errors as they occur, you can run _ Shadow 


Recording with write check for both disks of the shadowed pair. The 
MCR command: 


>SET /WCHK=ddnn: 


enables write check on the device that you specify in ddnn:. However, 
be aware that a write check of every write operation takes more time 
to execute than a write only. 


When write check is enabled, the Shadow Recording program prints’ the 
error messages on the console terminal. These error messages consist 
of device and logical block numbers when available. 


In the case of a read, the Executive reads from the primary disk 
first. If it encounters an error on the primary disk, it reads the 
same record from the secondary disk. It is unlikely that both disks 
would develop an error in exactly the same place. However, if they 
do, a notification of read errors on the secondary disk means that the 
primary disk is also bad in the same location. 


If read errors occur, several procedures can be followed, as discussed 
in the following subsections. 


18.3.1 Errors on the Primary Disk 


If errors occur when the Executive tries to read from the primary 
disk, the Executive tries to read the same record from the secondary 
disk. You are notified of the errors by a message on the console and, 
at this point, you may decide to let your task continue. If you do 
decide to let your task continue, be aware that the shadowed pair are 
no longer alike. 


If you decide not to let your task continue, stop the processing task 
(or tasks) and use the STOP command to stop Shadow Recording. The 
secondary disk contains all the data that was on the primary disk, 
including the bad block record. Use the secondary disk as the new 
primary disk. Designate a new device of the same type for the new 
secondary disk. Mount the new secondary disk on the secondary device 
as foreign. 


After mounting the old secondary disk on the primary device as the new 
primary disk, issue the START command. The START command causes the 
copying of the primary disk to the secondary disk, including the bad 
block record. 


18.3.2 Errors on the Secondary Disk 


If errors occur on the secondary disk, the shadow of the primary data 
is no longer valid. Shadow Recording should be stopped, a new 
secondary disk should be mounted, and Shadow Recording restarted. The 


catchup task will then copy the primary disk to the new secondary 
disk. 
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18.3.3 Errors on the Primary and Secondary Disk 


The simultaneous occurrence of bad data in the same blocks of two 
different disks is unlikely, and this kind of error is not 
recoverable. However, whether or not an error occurs at the same or 
different places on both disks, the only recourse is to stop Shadow 
Recording and your tasks. Then, select a new primary disk and new 
secondary disk, mark the bad block information on the new primary disk 
as before, and copy the old primary disk to the new primary disk. 


If the error occurred on different blocks on both disks, the 
previously processed information can be salvaged by using the old 
primary and secondary as a shadowed pair input to the Backup and 
Restore Utility (BRU). BRU copies all the data that is on the input 
disk and writes it to the output disk. If you use a shadowed pair as 
input to BRU, only the good data is written to the output disk because 
of the alternative read that the Executive does on the secondary disk 
if primary disk errors occur. 


Using BRU will not give you a new primary disk. You must create a new 
primary disk from the output of BRU as discussed in Section 18.1. 


Information about how to use BRU is in the RSX-11M/M-PLUS Utilities 
Manual. yi te OS oe 


18.4 SHADOW RECORDING MESSAGES 


hh:mm:ss -- Handler Error code-nn. on ddnn: 
Shadow Pair: ddnn: ddxx: 
Task: XXXxXxXx 
Logical Block: nnn. 
Bytes in xfer: nnn. 
File ID: n,n 
File Name: xxxxxx 
nn. errors lost due to saturation. 


Explanation: 
hh:mm:ss 

The time in hours, minutes, and seconds of the error. 
code-nn. 

The I/O error code (decimal) for the error. 


I/O error codes are summarized in the RSX-11M-PLUS 
Mini-Reference. 


File ID 
File Name 


The file ID and file name are printed only when they can be 
determined at the time of the error. 


nn. errors lost 


When an error occurs on ae shadowed disk, the Executive 
notifies the shadow error reporting task that prints the 
above message on the console terminal. The Executive stores 
the information about the error in pool _ for the error 
reporting task to pick up and print. 
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If more than fifteen errors occur rapidly, pool can fill up 
with error information before the error reporting task can 
process it. This may cause a_ shortage of pool, so that 
there may be no-_ pool left to run the system. To prevent 
this from occurring, the Executive allows only as_ many 
errors as it can process to be queued in pool at one time. 
If fifteen errors have already taken place, and still more 
errors occur, the Executive keeps track of the errors 
without processing them. The message "nn. errors lost" 
tells the user how many errors were ignored. The term 
"saturation" refers to pool being saturated with as_ many 
error messages as the Executive limit allows. 


This message is only printed when errors have not been 
processed. 


User Action: See Section 18.3, Bad Block Handling. 


-- Abort error 


Explanation: This message occurs if the Shadow Recording ABORT 
command cannot abort Shadow Recording during catchup. 


User Action: Wait until catchup terminates and then issue the 
STOP command. 

-- Bad indirect file specification 

Explanation: The indirect command file name is incorrect. 


User Action: Reissue the indirect command file specification. 


-~- Bad volume type 


Explanation: The disk is not in Files-1ll format or the primary 
and secondary devices are different device types. 


User Action: Check the command line or devices that you are 
trying to use. 
-- Catch-up completed 


Explanation: This is an informational message. The primary disk 
has been copied completely to the secondary disk. 


User Action: None. 


-- Catch-up in progress 


Explanation: You tried to issue a STOP command during the 
catchup process. 


User Action: Issue an ABORT command if catchup is still in 
progress. 
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-- I/O error on logical block nnn. 

Explanation: An I/O error occurred during catchup. 

User Action: None, unless the I/O errors are frequent. If the 
I/O errors are frequent, enter the ABORT command, change disks, 
and restart Shadow Recording. 


~~ Illegal command 


Explanation: The command that you enterec is not a legal 
command. 


User Action: Reenter the command. 
-- Input error on input command file 
FILE= 


Explanation: An error occurred while the indirect command file 
was being read. 


User Action: Take appropriate action; for example, use a 
different indirect command file, or use a copy of the specified 
command file. 


-- Illegal parse data (internal error) 


Explanation: This is an internal system error. The command was 
correctly entered. 


User Action: Reenter the command. 


-- Invalid device 
Explanation: The device is not a disk device. 


User Action: Check the device specification and the device. 


-- Maximum indirect command file depth exceeded 


Explanation: The indirect command file was nested to too many 
levels. Only three levels are allowed. 


User Action: Check the indirect command file. 


-- No room available for UMB 


Explanation: Not enough pool space exists to allocate space for 
the UMB control block for Shadow Recording. 


User Action: Check your system. The system may be on the verge 
of running out of pool space. 
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-- Not a shadowed pair 


Explanation: When STOP or ABORT was issued, the wrong device was 
specified. 


User Action: Reissue the command with the correct device unit. 
-- Open error on input command file 
FILE= 
Explanation: The input command file could not be found. 
User Action: Check the command file and its location. 
-- Privileged command 
Explanation: You are not using a privileged account or terminal. 


User Action: Log in on a privileged account or terminal. 


-- Send/Receive error 


Explanation: A Receive Executive directive error occurred in 
Shadow Recording during catchup. 


User Action: None. This is a system error. 


-- Shadow Recording not in system 

Explanation: Shadow Recording is not part of your system. 

User Action: Shadow Recording must be specified at system 
generation. 

-- Start-up error 


Explanation: Shadow Recording cannot spawn the catchup task, so 
Shadow Recording exits. 


User Action: Restart Shadow Recording. 


-- Syntax error 
Explanation: The entered command has incorrect syntax. 


User Action: Reenter the command. 


~- System error 
Explanation: A system error occurred. 


User Action: Determine the effects of the error if possible. 
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SHA -- Unknown command error 


Explanation: Shadow Recording received a command line that it 
could not recognize. 


User Action: Check the command that you entered or the indirect 
command file. 
SHA -- Volume currently part of shadowed pair 


Explanation: The specified device is already being shadow 
recorded. 


User Action: Check the devices being shadowed with the DISPLAY 
command. 
SHA -- Volume not mounted properly 


Explanation: The primary device is not mounted Files-ll, or the 
secondary device is not mounted foreign. 


User Action: Check the devices and mount them properly. 


18-15 


CHAPTER 19 


DISK DATA CACHING ON RSX-11M-PLUS AND MICRO/RSX SYSTEMS 


Disk data caching is a feature on RSX-l11M-PLUS and Micro/RSX systems 


that enhances I/O operations by reducing the number of physical I/O 
requests directed to a disk. 


The Data Cache Manager (DCM), also referred to as the "cacher", acts 
as an intelligent preprocessor to any disk driver. In addition to 
monitoring all I/O operations performed on disk devices, the DCM 
decreases the number of physical I/O operations taking place on 
"cached" disk drives by using a cache region in memory. Copies of 
disk data are placed in the cache region, making the data available 
for memory-to-memory transfers instead of disk-to-memory transfers 
during an I/O request. 


The DCM option is enabled by default on Micro/RSX systems and on 
pregenerated RSX-11M-PLUS systems. The DCM can be chosen as a system 
generation option for RSX-11M-PLUS systems; it is included as part of 
the Full-functionality Executive. 


Disk data caching must be activated explicitly for a disk. You can 
activate, disable, override, monitor, or modify disk data caching 
using the commands in Sections 19.4 and 19.5. 


19.1 DATA CACHE FEATURES 


Disk data caching is available for various types of I/O operations. 
Caching is most effective when blocks of data are read repeatedly or 
accessed sequentially in small increments. The following list 
describes types of I/O operations that can be enabled or disabled for 
data caching. 


e Directory 1/0 


Enabled by default, this operation can be disabled. All 1/0 
operations which are issued by an ACP task with context 
switching enabled are treated as "directory I/O" operations. 
Typically, this would be for files such as [0,O0]BITMAP.SYS;, 
[0,O0]INDEXF.SYS;, and the [0,0].DIR [directory] files. 


e Overlay Loads 


Enabled by default, this operation can be disabled. All 
IO.LDO and I0.LOV operations are cached depending on their 
size. If the load request is considered to be too large, then 


the request is not cached. This prevents overlay loads from 
monopolizing the cache buffers. 
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@® Data 1/0 


Enabled by default, this operation can be disabled. All 
IO.RVB and IO.WVB operations are cached. Operations which are 
issued by an ACP with context switching disabled are also 
considered data I/O, to differentiate them from directory I/O. 


@ User logical 1/0 


Disabled by default, this operation can be _ enabled. All 
IO.RLB and IO.WLB operations (not from an ACP) are considered 
logical I/O. Typically, tasks that use logical I/O are doing 
so for a special purpose. BRU, for example, reads file 
extents randomly throughout the disk. In this case, there is 
little to gain by caching this class of operations. 


@e Read ahead for virtual I/0 


Disabled by default, this operation can be enabled. When the 
highest block of a cache extent is read using a virtual read, 
then, if there is sufficient context, another extent of the 
file's data is loaded automatically by the cache, without 
having been requested by the user. The maximum number of 
blocks that can be read is the number of blocks in the extent 
or the number of blocks in the maximum extent size. This 
operation is beneficial for disks that contain numerous 
sequential files which are frequently accessed sequentially. 


Cache I/O is handled by the cache code. During a read operation for a 
type of I/O that is to be cached, the DCM intercepts an I/O request 
and checks the request against the data stored in memory. If the 
correct data is stored in memory, the DCM processes the request. If 
the cache does not contain the requested data, the DCM forwards’ the 
I/O request to the appropriate driver for processing. When the 
physical I/O completes, the DCM resumes processing by copying the 
appropriate portion of the data to the user's buffer. 


During a write operation for a type of I/O that is to be cached, the 
appropriate data is copied from the user's buffer to the corresponding 
cache buffer. If there is no corresponding cache buffer, the request 
is forwarded to the disk driver for processing, and the data is not 
cached. When the copy operation is finished, the DCM completes’ the 
I/O by passing the user's packet to SIOFIN. 


Special handling is required to ensure that the cache buffers reflect 
valid data for mounted disks’ only. For that purpose, the cache 
handles the IO.STC operation. Normally, IO.STC is issued by the MOUNT 
command as part of mount processing, and by DMOUNT as part of dismount 
processing (for /UNLOAD) in order to set hardware and software volume 
valid. When the cache manager receives the mount parameters, it 
initializes the cache (this may include purging the cache before 
initialization to prevent stale data from a removed disk pack from 
being used), and duplicates and dispatches the user's packet while 
retaining the original request. The status is returned to the user 
via SIOFIN. If the operation was successful, the related cache region 
use count is incremented, to prevent its deallocation. When a 
dismount packet is received, the user's packet is stalled until all 
outstanding buffers (if any) are written to the disk first. All 
further cache processing is disabled for that device. When the cache 
context for the drive is clear, the stalled dismount request is 
forwarded to the driver. 
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19.2 DATA CACHE MANAGER (DCM) 


The Data Cache Manager (DCM) is the code that provides data cache 
support. It resides in a directive common. The DCM is responsible 
for monitoring disk data cache operations. It ensures that disk data 
is stored in memory and that the data stored in memory is available 
for use during I/O requests. 


The DCM executes within the I/O system after all packet preprocessing 
and before disk driver activation. The DCM will execute if the device 
is a mass storage device (DV.MSD) and not a tape device (not DV.SQD). 
If the device to which an I/O request is directed is not a disk (or 
the cache support is not within the Executive), the driver will be 
mapped and activated at the initiation entry point. The positioning 
of the DCM at this point in processing allows all I/O packets to be 
intercepted when all but the driver processing (including the 
placement of the request into the device queue) has been performed for 
the packet. 


In order for the cacher to run, regions must be established for 
caching, and the devices which are to use them must be notified. This 


requires that the appropriate commands be used to define and enable 
caching (see sections 19.4 and 19.5). 


19.2.1 PERMANENT DCM IN A SYSTEM CONFIGURED USING VMR 

The following VMR commands are provided in SYSVMR.CMD to permanently 
include disk data caching as a directive common in the bootstrapped 
system: 


INS DCMEXP 
FIX DCMEXP/DIR 


19.3 THE DATA CACHE REGION 


A data cache region must be created and formatted before caching is 


activated. If you want to use a region other than the default region 
provided by the system, you must specify the region name when you 
create a cache’ region. When the device(s) associated with a cache 


region has completed processing, the cache region is deactivated (but 
not deleted) by a DISMOUNT or SET command. Section 19.4 describes the 
DCL commands used to specify, create, and deactivate a cache region. 
Section 19.5 describes MCR commands to specify, create, and deactivate 
a cache region. 


The data cache region contains extents. Extents are ranges of 
physically contiguous memory blocks which are memory-resident copies 
of ranges of physically contiguous disk blocks. These blocks’ are 
tagged with their corresponding disk logical block numbers (LBN) so 
that they can be found in the cache. 


The blocks of disk data are stored in a cache region during a request 
for a read operation or when read-ahead is enabled. If read-ahead is 
enabled, blocks of data residing in the same extent as a read request 
are also placed in the cache region. As blocks of data are placed in 
a cache region, they are tagged with their LBNs so that the data can 
be found during a subsequent I/O request. 
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To maintain a data cache region, adequate memory must be available to 
hold copies of the disk data in the cache region. You can use the 
SHOW command to monitor a cache region as well as the activity of the 
DCM. See Sections 19.4.2, 19.5.2, and 19.5.3 for information on 
monitoring a data cache operation. 


Typical RSX-11M-PLUS and Micro/RSX systems define one main partition 
for general use. This partition, named GEN by default, may contain 
many regions. These regions can be commons, Extended Executive 
Partitions (EXP), and task images. For disk caching purposes, a 
region is used to contain the cache-specific data structures and disk 
data buffers. This region can have any name. It is marked with the 
following PCB status bits: 


P.STAT 
PS.FXD - Region is fixed in memory 
PS.NSF - Region is not shuffleable 
PS.COM - Region is a common 


P.PRO - Protection word blocking all access [,,,] 


P.ST2 
P2.RON -— Read only (external users) 
P2.APR —- Depends on Executive: 
P2.APR = 5 for I/D systems 
P2.APR = 6 for non-I/D systems 
P2.LMA - Do not remove this region 
P2.CHE - Cache region (informational only) 


Cache regions may be shared by multiple devices, or one region may be 
used exclusively by one device. When caching is enabled for a device, 
the system default cache region, named CACHE, is used unless’ another 
region is specified. This “other" region must be created and 
formatted for the cacher to be able to use it. The region may also be 
in use by another device that has caching enabled. 


19.3.1 CREATION AND DELETION 


Data cache regions are allocated and deallocated by the appropriate 
commands. The region is formatted at the time of creation. When data 
caching is enabled for a disk device, the Unit Control Block Extension 
(UCBX) is marked with the address of the data cache region (PCB). To 
force the binding of the region with the device to prevent illegal 
deallocation, the P.RMCT field (resident, mapped task count) reflects 
the number of devices which currently have caching enabled for that 
region. The region cannot be deleted as long as P.RMCT is non-zero. 
When there are no devices with access for that region, P2.LMA is 
cleared, allowing the region to be removed from the system. 


19.3.2 FORMAT 


The data cache region has two parts. (See Figure 19-1.) The beginning 
of the region contains pool space. Non-I/D systems map pool through 
APR 6 and have a 4KW limitation; I/D systems map pool through data 
space APR 5 and APR 6 with an 8KW limitation. The standard SALOCB 
(entry point SALOC1) and $DEACB (entry point $DEAC]), which are _ the 
pool allocation and deallocation routines within the Executive, are 
used to allocate and deallocate space from this area. The dynamic 
data structures, which are cache-specific, are retained in this area 
to minimize the load of data caching on the primary pool resource. 
The remainder of the cache region is used to buffer disk data blocks. 
It is allocated on 32-word boundaries in 256-word increments. 
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The Cache Extent Descriptor (CED) is a data structure within 


the 


region's pool that describes all data buffer space in the cache 
region, whether the space is in use or not. This allows contiguous 


blocks of space to be reclaimed when needed. 


Cache-specific pool 


Disk data buffer space 


ZK-4187-85 


Figure 19-1: Format of Data Cache Region 


The pool area of the cache region contains a header which is used 
control various region-specific structures. (See Figure 19-2.) 


H.CSTS 
H.1OC 


H.PAVL 
H.PKTQ 


H.CMDH 
H.CEDH 


H.TEMP1 
H.TEMP2 
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+00 


+02 


+10 


+14 


+20 


+24 


+26 


Figure 19-2: Format of Pool Header Area 


H.CSTS Region code status. The following bits are 
defined in this byte: 


CS.REQ 
CS.RIN 
CS . DNF 


nol tt 
BNE 
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H.IIOC 


H. PAVL 


H.PKTQ 


H.CMDH 


H.CEDH 


H.TEMP1 


H.TEMP2 


Region internal I/0 count. This is not 
used by the data cache. 


Pool available list. This is a standard 
3-word pool list head, which contains the 
alignment word followed by the list head, 
which is a pointer to the next available 
block and the size of the block. 


Pending packet queue (in descending 
priority order). These packets are 
waiting for data cache completion 
processing. They either have I/O in 


progress, are waiting for data movement to 
begin, or are waiting to be dispatched to 
either the user [SIOFIN] or the driver. 


List head for region buffer space 
allocation. 


List head for CEDS ordered by age (the 
oldest are at the head of the queue). 


Pointer used in allocating new extents 


Pointer used in allocating new extents 


The region is formatted before caching is enabled on any dependent 


disk devices. 


19.4 DCL COMMANDS USED WITH DISK DATA CACHING 


This section describes the DCL commands and qualifiers you use 


the following: 


e Associate 


caching with a device 


e Specify the type of caching you want enabled 


@e Monitor data cache operations 


@e Modify data cache operations 


19.4.1 MOUNT Command 


The MOUNT command 
the MOUNT command. 


Format 


to 


makes a disk volume available for processing. 
associate caching with a selected disk, use the /CACHE qualifier with 


MOUNT ddnn:volumelabel /[NO]JCACHE[: (option,option,...)] 


Parameters 


ddnn: 


Specifies the device on which the volume is to be mounted. 


volumelabel 


Specifies the name that is associated with that volume. 
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Qualifiers 


/ CACHE 


Lets you associate caching with the specified disk, and allows 


you to override the disk data caching defaults and set one or 
more of the options. 


The following options are available with disk data caching: 

CREATE[:[region][£:[main partition][:[cache size]]]] 

REGION: name a 7 

[NO ]DIRECTORY[:extent_size] 

([NO]JLOGICAL[ :extent_size] 

[NOJOVERLAY[ :extent_size] 

[NOJREAD_ AHEAD[:extent_size] 

[NO]JVIRTUAL[ :extent_size] 
The extent_size argument specifies the maximum size of an I/O 
request that will be considered for caching. The extent size 
radix is decimal. The minimum value for an extent size is 1; the 
maximum is 15. Extent sizes can be modified for cached devices 
using the SET command. 


/NOCACHE 


Specifies that caching is not associated with the device being 
mounted. 


Options 
CREATE[ :(region][{:{main_partitionJ[:(size]]]] 


Creates a cache region and associates caching with the specified 
device in that region. 


The default name for the region is CACHE; the default name _ for 
the main partition is GEN. The default size is 100(decimal) disk 
blocks. 


REGION : name 


Associates caching for the specified device with an already 
existing cache region. 


You can specify a region to be used in place of the system 
default. The default region is CACHE. 


[NO JDIRECTORY[:extent size] 


DIRECTORY enables caching of directory I/O. This is the system 
default and need not be specified. 


NODIRECTORY disables caching directory 1/0. You must’ specify 
this option if you want to disable caching of directory I/O. 


The default extent size for DIRECTORY is l. 
[NO JLOGICAL[ :extent_size] 


LOGICAL enables caching of logical I/O. You must’ specify this 
option if you want to enable caching of logical I/O. 


NOLOGICAL disables caching of logical I/O. This is the default. 


The default extent size for LOGICAL is l. 
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CNO JOVERLAY[ :extent_size] 


OVERLAY enables caching of overlay I/O. This is the system 
default. 


NOOVERLAY disables caching of overlay I/O. You must specify this 
option if you want to disable caching of overlay I/O. 


The default extent size for OVERLAY is 4. 


[NO]READ AHEAD[ :extent_size] 


READ AHEAD enables reading of data (for virtual 1/0) before 
explicitly requested. You must specify this option if you want 
to enable reading of data before explicitly requested. 


NOREAD AHEAD disables reading of data before it is explicitly 
requested. This is the default. 


The default extent size for READAHEAD is 5. 
C[NO]VIRTUAL[ :extent_size] 


VIRTUAL enables caching of virtual I/O. This is the system 
default. 


NOVIRTUAL disables caching of virtual I/O. You must specify this 
option if you want to disable caching of virtual I/O. 


The default extent size for VIRTUAL is 5. 


19.4.2 SHOW CACHE Command 


Once disk data caching is established through the MOUNT or SET 
command, you can monitor the performance of data caching using the DCL 
command SHOW CACHE. This command allows you to display system 
information on data caching. To display data cache information on a 
specific device, you must supply the device name on the command line. 


Format 

SHOW CACHE [/DEVICE=ddnn:] [/REGION=name] [/RATE:n] 
Qualifier 

/DEVICE=ddnn: 


Specifies the device about which you want to display detailed 
data cache information. Note that /DEVICE and /REGION cannot be 
used together. 


/REGION=name 
Specifies the cache region about which you want to display 
general data cache information. Note that /DEVICE and /REGION 
cannot be used together. 


/RATE:n 


Specifies in seconds the rate at which the screen refreshes. The 
default rate is 1 second. 
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19.4.3 SHOW DEVICE Command 
Once disk data caching is established through the MOUNT or SET 
command, you can list cached devices using the DCL command SHOW 
DEVICE. This command displays information about devices recognized by 
the system. To display information about a particular device, you 
must specify the device name on the command line. 
Format 

SHOW DEVICE [ddnn:] /[NO]CACHE 
Parameter 
ddnn: 

Specifies the device for which you are displaying information. 
Qualifier 


/ CACHE 


Lists all devices known to the system that are cached (if no 
device is specified). 


/NOCACHE 


Lists devices that are not cached, but could be cached. 


19.4.4 SET DEVICE Command 


To modify data caching on your system, or to associate caching with a 
device, use the DCL command SET DEVICE. This command allows you to 
modify various system values and behavior. To modify the behavior or 
the value of specific devices, you must supply the device name. Note 
that a region associated with a specific device cannot be modified 
while caching is enabled for that device. 


Format 
SET DEVICE ddn: /[NOJ]CACHE[: (option,option,...)] 
Parameter 
ddnn: 

Specifies the device you are modifying. 
Qualifiers 
/ CACHE 


Modifies the data caching behavior for the specified device. You 
may modify the following options: 


CREATE[ :region][:{main_partition][:[cachesize]]]] 
REGION : name 

CNO]DIRECTORY[ :extent_size] 

[NO JLOGICAL[:extent_ size] 
[NOJOVERLAY[:extent_size] 

[NO]JREAD AHEAD[:extent size] 

[NO]VIRTUAL[ :extent_size] 
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The extent size argument specifies the maximum size of an 


I/O 


request that will be considered for caching. The extent size 


radix is decimal. The minimum value for an extent size is l; 


the 


maximum is 15. Extent sizes can be modified for cached devices 


using the SET command. 
These options are described in Section 19.4.1. 
/NOCACHE 


Deactivates caching for the specified device. 


19.5 MCR COMMANDS USED WITH DISK DATA CACHING 


This section describes the MCR commands and qualifiers you use to 


the following: 
e Associate caching with a device 
e Specify the type of caching you want enabled 


@e Monitor data cache operations 


Modify data cache operations 


19.5.1 MOUNT Command 


The MOUNT command makes a disk volume available for processing. 


do 


TO 


associate caching with a selected disk, use the /CACHE qualifier with 


the MOUNT command. 
Format 

MOUNT ddnn:volumelabel /[NO]CACHE[: (option,option,...)] 
Parameters 
ddnn: 

Specifies the device on which the volume is to be mounted. 
volumelabel 

Specifies the name that is associated with that volume. 
Qualifiers 


/CACHE 


Lets you associate caching with the specified disk, and allows 
you to override the disk data caching defaults and set one or 


more of the options. 
The following options are available with disk data caching: 


CREATE[: [region] [: [main partition] [: [cache size]]]] 
REGION: name * 

{NO]DIRECTORY[:extent size] 

[NO]LOGICAL[:extent size] 

[NO]OVERLAY [:extent size] 

[NO]READ AHEAD[:extent_ size] 

[NO] VIRTUAL [:extent_size] 
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The extent size argument specifies the maximum size of an I/O 
request that will be considered for caching. The extent size 
radix is decimal. The minimum value for an extent size is 1; the 
maximum is 15. Extent sizes can be modified for cached devices 
using the SET command. 

/NOCACHE 


Specifies that caching is not associated with the device being 
mounted. 


Options 
CREATE[:[region][:{main_partition][:[size]]]] 


Creates a cache region and associates caching with the specified 
device in that region. 


The default name for the region is CACHE; the default name _ for 
the main partition is GEN. The default size is 100(decimal) disk 
blocks. 

REGION :name 


Associates caching for the specified device with an already 
existing cache region. 


You can specify a region to be used in place of the system 
default. The default region is CACHE. 


[NO ]DIRECTORY[:extent_size] 


DIRECTORY enables caching of directory I/O. This is the system 
default and need not be specified. 


NODIRECTORY disables caching directory I/O. You must’ specify 
this option if you want to disable caching of directory I/O. 


The default extent size for DIRECTORY is l. 
(NO ]JLOGICAL[:extent_size] 


LOGICAL enables caching of logical I/O. You must specify this 
option if you want to enable caching of logical I/O. 


NOLOGICAL disables caching of logical I/O. This is the default. 
The default extent size for LOGICAL is l. 
[NOJOVERLAY[ :extent_ size] 


OVERLAY enables caching of overlay I/O. This is the system 
default. 


NOOVERLAY disables caching of overlay I/O. You must specify this 
option if you want to disable caching of overlay I/O. 


The default extent size for OVERLAY is 4. 
([NO]READ_AHEAD[:extent_size] 
READ AHEAD enables reading of data (for virtual 1/0) before 


explicitly requested. You must specify this option if you want 
to enable reading of data before explicitly requested. 
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NOREAD AHEAD disables reading of data before it is explicitly 
requested. This is the default. 
The default extent size for READAHEAD is 5. 
[NO ]VIRTUAL[ :extent_size] 


VIRTUAL enables caching of virtual 1/0. This is the system 
default. 


NOVIRTUAL disables caching of virtual I/O. You must specify this 
option if you want to disable caching of virtual I/O. 


The default extent size for VIRTUAL is 5. 


19.5.2 RMD C Command 


Once disk data caching is established through the MOUNT or SET 
command, you can use the RMD command to monitor performance. 


The RMD command allows you to display various pages of system 
information. The RMD C command allows you to display the C page, 
which shows general statistics about a particular cache region. After 
you analyze this information, you can use the SET command to modify 
system values and behaviors to possibly enhance performance. 

Format 

RMD C [,REGION=region][ ,RATE=nn] 


Setup Commands 


REGION 
Selects the cache region to be displayed. The default region is 
CACHE. 

RATE 
Specifies the number of seconds between screen refreshes. The 


default is 1 second. 
Example 


Figure 19-3 is a sample RMD C page display; it is followed by an 
explanation. 


RSX-1LiM-FLUS V3.0 EL21B Cache Statistics (General) PI-MAR-BS 09249239 
@ cache Region Names CACHE @ Resion Size: 5900Q (288. disk blocks) 
evice Total Hit Fail Load Total Hit Fail Tlefer Tatal Cache 
Name Reacts Rate Rete Rate Writes Rate Rate Rate T/O Nes Used 
DR43 117165. 692% 3% 182 256h6. E94 0% O% 142831. &5% 
IRS? 21491. 27% 2% 59% 12334, Bb% O% O% 34027. 3aZ 
® total 138856. 63% 3% 252% 38002, EA OZ O% 176858. G9% 


ZK-4184-85, 


Figure 19-3: RMD C Page Display 
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Cache Region Name indicates the name of the cache. 


Region Size shows the actual memory size in octal of the 
cache region in 32-word memory blocks. This size includes 
the private cache pool area as well as the extent storage 
area. The second part of thé size field displays the size of 
the extent storage area in disk blocks. 

The Total Reads field displays the count of all read requests 
issued to that device. These include VIRTUAL, READAHEAD, 
DIRECTORY, LOGICAL, and OVERLAY read requests. 


The Hit Rate is the percentage of all read requests that were 
satisfied by the cache. 


The Fail Rate is the percentage of all read requests’ that 
could not be satisfied by the cache because of an extent 
overlap or a cache pool allocation failure, or because the 
request size exceeded the specified extent size limit. 
Actual errors in loading the cache from the disk are not 
counted in this rate. 


The Load Rate is the percentage of all read requests’ that 
resulted in data being loaded into the cache. The total of 
the Hit, Fail, and Load rates should be close to 100%. The 
total may not always equal 100%, because read requests can 
fail because of a primary pool allocation failure, which is 
not associated directly with read or write requests. The 
failure rate of primary pool allocation is shown on the RMD D 
page; it should be small. 


The Total Writes field displays the count of all write 
requests issued to that device. These include VIRTUAL, 
DIRECTORY, and LOGICAL write requests. 


The Hit Rate is the percentage of all write requests’ that 
caused updating of blocks already loaded in the cache. 


The Fail Rate is the percentage of all write requests that 
could not be directed to the cache because of an extent 
overlap. The Hit Rate and Fail Rate will not total 100%, 
because a write miss is not considered a write failure. 
Also, write requests to a cache can fail because of a primary 
pool allocation failure, which is not associated directly 
with read or write requests. The failure rate of primary 
pool allocation is shown on the RMD D page; it should be 
small. 


The Defer Rate is the percentage of all write requests that 
were deferred; that is, the actual write operation to the 
disk was done some time after the user's write request was 
completed. 


The Total I/O Operations is the total of all read and write 
operations for that device. 


The Cache Used field indicates the percentage of the cache 
extent storage area used by the device. 


The bottom line displays the grand totals for the region. 
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19.5.3 RMD D Command 
The RMD D command allows you to display the D page of the RMD display, 
which shows detailed statistics about a particular cached device. 
After you analyze this information, you can use the SET command to 
modify system values and behaviors to possibly enhance performance. 
Format 

RMD DL, DEVICE1=ddnn: J[,, RATE=nn ] 
Setup Commands 


DEVICE] 


Specifies the device to be displayed. The default device is SY:. 


RATE 
Specifies the number of seconds between screen refreshes. The 
default is 1 second. 
Example 
Figure 19-4 is sample RMD D page display; it is followed by an 
explanation. 
RSX-11M-PLUS V3.0 BL21R Cache Statistics (Uetsiled) 21-MAR-85 09:46:02 
Device Names SYOG; 0 Region Neme$ CACHE Resion Sizes 3000 
2] Cache Status:t Active 3] Reauests Beind Cached? firrOversVir 
Virtual Readahead Iti rectors Lodical Overlay Total 
O Reads 77515. 0. PA75S. O. 14919. 114189, 
Read Hit Rate 73% O% 72% Q% 49% 59% 
© Read Load Rate 22% O% 17% 0% 4% 19% 
Read Overlar 0% 0% 2% O% 0% O% 
Extent Too &i¢ 3% OZ 0% O% 2h 2A 
@ Max Extent Size 5. Ss 1. 135 4, 
@ writes 12956. 12507. 105. 25548. 
o | Write Hit Rate AB% 91% O% 59% 
Write Overlar 0% O% ah O% 
@ Total 1/0 90471. 0. 34242, 105. 146919. 141757. 
Frimary Fool Allocation Failure Rate (as a % of Total 1/058) OZ 
© Cache Pool Allocation Failure Rate (as a % of Total Read I/0s)% O4 
Read Load Failure Rate (as a % of Cache Load I/0s)% O% 
Deferred Write Rate (as a % of Total Write I/0s): O% 
7«-4185-85 


Figure 19-4: RMD D Page Display 


@ The Region Name and Region Size fields are the same as in the 
C page description, except that the extent storage area size 
in disk blocks is not displayed. 


@ The Cache Status field shows whether the cache is ACTIVE 
and/or ENABLED. ACTIVE means the device is being cached 
through the region; ENABLED means that the device will 
automatically be cached when it is mounted (even if the MOUNT 
command does not explicitly request that the device be 
cached). 
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© The Requests Being Cached field shows the types of cache 1/0 
operations enabled for the device. The types can be VIRTUAL 
(VIR), READAHEAD (RDH), DIRECTORY (DIR), LOGICAL (LOG), and 
OVERLAY (OVR). 


4] The Reads section shows the number of read requests issued 
for each of the I/O types listed in the display, as well as 
the total of all read requests. 


5] These four lines show the Read Hit Rate, the Read Load Rate, 
the Read Overlap Rate, and the Extent Too Big rate for each 
type of request. Each of these rates is computed as a 
percentage of the total number of read operations for the 
particular type of request. 


@ The Maximum Extent Size for each of the I/O types. 


@ The Writes section shows the number of write requests issued 
for each of the I/O types and the total of all write 
requests. Note that READAHEAD and OVERLAY write requests do 
not exist, so these fields are blank. 


@ The Write Hit Rate and Write Overlap Rate for each type of 
I/O request. Each of these rates is computed as a percentage 
of the total number of write operations of a particular type. 


© The total amount of each type of I/O, as well as the _ total 
amount of all I/0. 


® The last four lines show rates that are not accumulated by 
I/O type. All cache I/O requests require that an I/O packet 
be allocated from primary pool. 


The Primary Pool Allocation Failure Rate line shows how often 
the allocation cannot’ be done as a percentage of the total 
number of I/Os issued for that device. 


The Cache Pool Allocation Failure Rate is similar to the 
failure rate for primary pool allocation, except that 
allocation from the cache pool is only required on read 
operations. The rate is therefore computed as a percentage 
of the total number of read operations. 


The Read Load Failure Rate is the percentage of all cache 
load attempts that failed because of an I/O error. 


The Deferred Write Rate is the rate that write operations 
were able to be deferred. This is computed as a percentage 
of the total number of write operations. 


19.5.4 DEV Command 


The DEV command displays system information about various devices. If 
no device is specified, then all the devices known to a system are 
listed. If a device but no unit is specified, then all the units of 
that device are listed with some minimum amount of status. If both a 
device and unit are specified, then the maximum amount of information, 
including the current cache attributes for that particular device, are 
displayed. 


Format 


DEV [dd[nn]:] 
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t 


Parameters 
dd: 
Specifies the devices about which information will be displayed. 


nn 


Specifies the unit of a particular device, about which 
information will be displayed. 


19.5.5 SET Command 


The MCR command SET allows you to display and modify various’ system 
values and behaviors; it also allows you to associate caching with a 
device. If no device is specified, then all the devices with a 
corresponding cache status are listed. If a device is specified, then 
the current cache behavior for that device is modified appropriately. 
The region size can only be specified when you create a cache region 
(see the CREATE option). The region name can only be modified while 
all types of caching are disabled for that device (see the REGION 
option). 


Format 
SET /[NO]JCACHE[:ddnn:[(option,...)]] 
Qualifiers 


/ CACHE 


If no device is specified, lists devices with disk data caching 
enabled. If a device is specified, enables caching or modifies 
the caching behavior. 

/NOCACHE 


Lists devices with disk data caching disabled. You can specify a 
device but no options with the /NOCACHE qualifier. 


Argument 
ddnn: 
Specifies the device to be modified. 
Options 
The following options are available with disk data caching: 
CREATE[ :[region][:[main_partition][:[size]]]] 
REGION: name 
([NO]DIRECTORY[ :extent_size] 
[NO ]LOGICAL[ :extent_size] 
CNOJOVERLAY[:extent_size] 
[NO]JREAD AHEAD[:extent_size] 
[NO]JVIRTUAL[ :extent_size] 


These options are described in section 19.5.1. 
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SERIAL DESPOOLER TASK 


The Serial Despooler Task (PRT...) provides a means of eliminating 
contention for the system line printer. Rather than waiting for the 
line printer to become available, a task directs the output intended 
for the line printer to a disk file. The task issues a Send Data 
directive to the serial despooler, placing a data block that 
identifies the file to be spooled in the serial despooler queue. A 
Request. directive is then issued by the task to activate the _ serial 
despooler, in case it is not already active. PRT handles FCS-created 
files, but RMS files can be read only if they are sequential. All 
files identified in the serial despooler queue are printed in 
first-in/first-out (FIFO) order. 


You may wish to compare the capability of this task with the RSX-11M 
Queue Manager and its associated despooler. See Chapter 7 for more 
information about the Queue Manager. 


A.1 RECEIVE QUEUE OPERATION 


The standard method of placing a user file in the serial despooler 
receive queue (and requesting its execution) is through the PRINTS 
macro call, which is described in the RSX-11M/M-PLUS and Micro/RSX 1/o 
Operations Reference Manual. Files are spooled in this same manner by 
the RSX-11 utilities that support the spool (/SP) option. Each entry 
in the serial despooler receive queue consists of a 13-word data block 
containing the file-related information illustrated in Figure A-l. 


A.2 TEXT REQUIREMENTS 


The serial despooler task prints ASCII text with a maximum line length 
of 132 bytes. It will properly handle files with all modes of FCS 
carriage control (that is, standard, embedded, and FORTRAN). 


A.3 TASK-BUILD INFORMATION 


The serial despooler task must be built during an RSX-11M_ system 
generation because the task image file (PRT.TSK) is not distributed on 
the standard release kits. Normally, the serial despooler is built to 
retain all files that have been spooled, but the serial despooler 
build file can be edited during system generation to enable the 
automatic delete feature. (Note also, that a nondeleting despooler 
can be made to delete, if the data block mentioned in Section B.1 and 
shown in Figure A-l has a negative value in word 7.) When the serial 
despooler is built without automatic delete, spooled files are 
retained after printing. If the system has a deleting serial 
despooler, all spooled files are deleted after printing. 
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SERIAL DESPOOLER TASK 


See the RSX-11M System Generation and Management Guide for detailed 
system generation information. 


WORD 


1 File name 

2 in 

3 RADIX-50 

«| eile eee ie mons 
5 File version (binary) 
<[aeice mae in nacre 
[ante waar tine 
8 

9 File ID 
10 
ll 
12 Directory ID 
13 


Figure A-l PRT Send Data Buffer Format 


The serial despooler is set to spool files to LPO:. It uses LUN3 as 
the spool device. The system manager can redirect print files to any 
record-oriented device (that is, a device similar to the printer) by 
reassigning LUN3. See the RSX-11M/M-PLUS MCR Operations Manual for 
information on the REASSIGN command. 


A.4 PRT ERROR MESSAGES 


All error messages issued by PRT are sent to the console terminal 


through pseudo-device CO:. The error messages have the following 
format: 
PRT -- text 


All messages (except for the receive failure error) supply information 
that identifies the sender task and the file in question. All PRT 
errors are fatal; once an error is detected, PRT terminates printing 
of the input file, and a cleanup/restart procedure is entered. 


In the case of the receive failure error, the sender and file 


information are unavailable. Furthermore, PRT does not attempt to 
dequeue additional spool requests because of the nature of this error 
condition. Instead, PRT exits causing its receive queue to be purged 


by the system. 
RECEIVE FAILURE, d. -- TASK EXITING 
Explanation: The Receive Data or Exit directive failed while 


attempting to obtain the next file specifier from the queue. The 
system error code (d.) is printed to identify the error. 
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NO DEVICE NAME - SENDER: task FILE: filename.typ;ver 


Explanation: The dequeued print request did not contain a device 
name. 


NO FILE ID - SENDER: task FILE: filename.typ;ver 


Explanation: The dequeued print request did not contain a file 
ID. 


OPEN FAILURE INPUT FILE - SENDER: task FILE: filename.typ;ver, d. 


Explanation: The specified file could not be opened. One of the 
following six conditions may exist: 


1. The file is protected against access for read privileges. 


2. A problem exists on the physical device (for example, device 
cycled down). 


3. The volume is not mounted. 
4. The specified file directory does not exist. 
5. The named file does not exist in the specified directory. 
6. The file is already deleted. 
The system error code (d.) is printed to identify the failure. 
ATTACH FAILURE - SENDER: task FILE: filename.typ;ver, d. 
or 
DETACH FAILURE - SENDER: task FILE: filename.typ;ver, d. 
Explanation: The line printer could not be attached/detached 
(that is, the system does not contain a line printer). The 
system error code (d.) is printed to identify the error. 


PRINT ERROR - SENDER: task FILE: filename.typ;ver, d. 


Explanation: A Queue I/O request to the line printer has failed. 
The system error code (d.) is printed to identify the error. 


I/O ERROR INPUT FILE - SENDER: task FILE: filename.typ;ver, d. 


Explanation: An error was detected while reading the input file. 
One of the following three conditions may exist: 


1. A problem exists on the physical device (for example, device 
cycled down). 


2. The length of the text line is greater than 132 bytes. 

3. The file is corrupted or the format is incorrect. 

The system error code (d.) is printed to identify the error. 
d. LINES WERE TRUNCATED 


Explanation: While printing the file, PRT truncated d. lines. 


APPENDIX B 


RSX-11M/M-PLUS UFD CONVENTIONS 


The RSX-11M and RSX-11M-PLUS operating systems observe a set of User 
File Directory (UFD) conventions for files on disk. These conventions 
provide a consistent method of locating, allocating, and maintaining a 
file on disk. 


A UFD is itself a file, named in the format gggmmm.DIR where g and m 
are octal numbers in the range 1 through 377 (0 is reserved). The 
numbers represent the file owner's group and member number 
respectively. For more information on file ownership and directories, 
see the RSX-11M/M-PLUS MCR Operations Manual, the RSX-11M Command 
Language Manual, and the RSX-11M-PLUS Command Language Manual. 


The usage of certain UFDs is common to both operating systems; other 
UFDs are specific to the RSX-11M or RSX-11M-PLUS operating systems. 
The following sections describe group and member numbers and their use 
in identifying the contents of system UFDs. A section on file naming 
conventions is also included. 


B.1 GROUP NUMBER 


The group number identifies groups of directories. By convention, 
group numbers 1 through 200 are reserved by DIGITAL for system files, 
and group numbers 201 through 377 are reserved for user files. The 


group numbers may vary between RSX-11M and RSX-1l1M-PLUS. Table B-1 
lists the group numbers and their usage. 


Table B-l 
Group Number Identification 


Group Number Usage 
11 Executive files 
12 MCR files 
13 FCP files (RSX-11M-PLUS) 
14 RMD files 
15 Privileged utility tasks 
23 DCL files 


(continued on next page) 


Group Number 


25 
27 
45 
50 

121 

125 

126 


200 


B.2 MEMBER NUMBER 


RSX-11M/M-PLUS UFD CONVENTIONS 


Table B-1 (Cont.) 
Group Number Identification 


Usage 


Queue Manager files 

On-line configuration (RSX-11M-PLUS) 
K-Series files 

FCS files 

Line printer despooler (RSX-11M-PLUS) 
Shadow Recording (RSX-11M-PLUS) 
Accounting tasks (RSX-11M-PLUS) 


SYSGEN Indirect command files 


The second number (member number) identifies the different file 


within each group. 


Member Number 


10 


20 


24 


30 


34 


40 


50 


Table B-2 lists the member numbers. 


Table B-2 
Member Number Identification 


File Types 


Source modules 


types 


Object modules, assembly and task-build 
command files, and object module libraries 


for RSX-11M nonprivileged tasks 
RSX-11M/M-PLUS build files 


and 


Object modules, assembly and task-build 
command files, and object module libraries 


for the RSX-11M/M-PLUS Executive and 
privileged and nonprivileged tasks 
RSX-11M-PLUS 


for 
on 


RSX-11M unmapped system listing and map 
files for privileged and nonprivileged 


tasks 


RSX-11M-PLUS and RSX-11M mapped system 


listings and map files for privileged 
nonprivileged tasks 


and 


SLP correction files for files located 


under member number 10 


RSX-11M unmapped system image and task 


image files 
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Table B-2 (Cont. ) 
Member Number Identification 


Member Number File Types 


54 RSX-11M-PLUS and RSX-11M mapped system 
image and task image files 


60 RSX-11S° unmapped system SLP and PAT 
correction files applied by Update, and 
system image and task image files 


64 RSX-11S mapped system image and task image 
files 
200 SYSGEN Indirect command files 


B.3 EXAMPLE SYSTEM USER FILE DIRECTORIES 


The system UFDs consist of a group number and a member number. These 
numbers identify the specific contents of each directory. For 
example, if you wanted to locate all the MCR listing and map files, 
you could find the group number for MCR files (12) and the member 
number for listing and map files (34) and combine them to specify the 
UFD [12,34]: this UFD contains the MCR listing and map files. 
Table B-3 lists the MCR UFDs and the files contained in each UFD. 
Table B-4 lists the UFDs used by the RSX-11M/M-PLUS operating system. 


Table B-3 
MCR User File Directories (UFDs) 


[12,10] MCR source files 

[12,20] Unmapped MCR object modules, assembly 
command files, and library build command 
file 

[12,24] Mapped MCR object modules, assembly command 
files, and library build command file 

[12,30] Unmapped MCR listing and map files 

[12,34] Unmapped MCR listing and map files 

[12,40] SLP correction files for files under 
[12,10] 

Table B-4 


System UFDS 


[1,1] System and macro object module libraries 
[1,2] System message and help files 
[1,3] Lost files found by VFY 


(continued on next page) 


[1,4] 


[1,6] 


re a 


C1,11] 


[1,20] 


[1,24] 


[1,34] 
[1,54] 
[2,300] 
[200,1] 


[200,2] 
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Table B-4 (Cont.) 
System UFDS 


Postmortem and snapshot dumps 


Error logging files and, on 
Accounting 


RSX-11M-PLUS, 


Spooling queue file and transparent listing 
file 


RSX-11M-PLUS work space for system 
maintenance 

RSX-11M object module libraries and 
task-build overlay descriptor files for 


nonprivileged tasks 

Object module libraries, task-build command 
files for mapped tasks, and overlay 
descriptor files for privileged tasks 
Executive and task maps 

Executive and system tasks 

UETP files 


Sample files for system introduction 


Field service files 


B.4 SYSTEM FILE-NAMING CONVENTIONS 


System file names have the following general format: 


nnnsss.typ 


where: 


nnn 


sss 


typ 


The system identification for the task. 


For example, DMP 


is the identification for the File Dump Utility Program. 


A suffix for noting the relationship of the file to 


task specified 


the 


in the nnn identification. For example, 


PIPBLD.CMD is the command file for building PIP. 


Suffixes: 


The standard mnemonic for file type. 


a 


used to reflect the contents of a file. 


ASM 
BLD 


RES 
FSL 


of 


Assembly command file 

Task Builder command or overlay descriptor 
file 

FCSRES version of the task 

FCSFSL version of the task (RSX-11M-PLUS) 


RSX-11M/M-PLUS has 
and default file types that are 
See Table B-5. 


conventional 
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Table B-5 
System File Types 


Type File Contents 

-BAS BASIC-11 language source file 

- BAT Batch file 

-BLD Indirect command file used as input to SYSGEN 

-B2S BASIC-PLUS~2 language source file 

-CBL COBOL language source file 

-CDA Crash dump binary file 

-CFS Error logging control file string 

-CLB Indirect Command Processor command file library 

-CMD Indirect command file 

-COR SLP correction file 

-CRF Cross-Reference Processor symbol table file 

-DAT File containing data (as opposed to a program) 

-DIR Directory file 

- DMP File Dump Utility output file 

- ERR Error Logger output file 

- FTN FORTRAN IV, FORTRAN IV-PLUS or FORTRAN 77 language 
source file 

-HLP Help file 

- LOG Batch or console log file 

-LST Listing file 

-MAC MACRO-11 source file 

-MAP Task Builder memory allocation map 

-MLB Macro library file 

- OBJ Object module (output from either the MACRO-11 
Assembler or a compiler) file 

-ODL Task Builder overlay descriptor file 

-OLB Object module library file 

-PAT PAT Utility Correction file 

- POB Patched object module used by the PAT Utility 
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Type 


-SML 
-STB 
-SYS 
- TMP 
-TSK 
~-TXT 


-ULB 
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Table B-5 (Cont.) 
System File Types 


File Contents 


System macro library file 

Task symbol table file 

Bootable system image or other system file 
Temporary file 

Task image file 

Text file 


Universal library file 


INDEX 


/7ABAUD keyword (VMR), 10-53 
ABORT command 

IOX, 4-24 

Shadow Recording, 18-7 


Account File Maintenance Program 
See ACNT 
Accounting Startup Transaction 
Block, 17-25 
ACNT, 1-1, 2-1 
Account entry 
contents, 2-1 
deleting, 2-9 
examining, 2-5 
listing, 2-8 
modifying, 2-7 
Account file 
maximum number of entries, 
2-3 
sorting, 2-10 
account file 
copying, 2-3 
extending, 2-3 
changing password, 2-1 
copying account file, 2-3 
error messages, 2-11 
ESCAPE key, 2-3 
invoking, 2-2 
options, 2-2 
Add, 2-3 
Create, 2-3 
Delete, 2-9 
Examine, 2-5 
Exit, 2-11 
List, 2-8 
Modify, 2-7 
Sort, 2-10 
password encryption, 
protection 
restoring, 
ACSUB, 17-17 
Activity report 
IOX, 4-20, 4-42 
Add option 
ACNT, 2-3 
/AFF keyword (VMR), 10-22, 10-54 
Allocate Device Transaction Block, 
17-27 
ALT 
See ALTER command 
ALTER command (VMR), 
definition, 10-8 
example, 10-8 
format, 10-8 
keyword 
/PRI, 10-8 
parameters, 
/ANSI keyword 
ASN 
See ASSIGN command 


2-1 


2-3 


(VMR) 
10-8 


10-8 


(VMR), 10-54 


(VMR) 


ASSIGN command (VMR), 
definition, 10-9 
examples, 10-10 
formats, 10-9 
keywords 

/GBL, 10-10 
/SYSTEM, 10-10 
parameters, 10-9 

ASSIGN/QUEUE command 
DCL, 7-9 
MCR, 7-9 

/AVO keyword (VMR), 10-54 


10-9 


Backus-Naur Form metalanguage, 
12-6 
Bad block 
bad block replacement functions, 
5-1 
detection, 
handling 
MSCP disks, 
listing 
IOX, 4-26 
notification, 5-1, 5-3 
recovery techniques, 5-1 
removing from testing 
IOX, 4-25 
replacement, 5-l, 
partial, 5-4 
revectoring, 5-l, 
specifying 
IOxX, 4-25 
Bad Block Replacement Control 
Task, 1-2 
See also RCT, 
BADBLOC KS 
display command, 
IOX command, 4-25 
parameter command, 4-25 
Base priority for nonprivileged 
,; tasks, 13-13 
Batch processing, 
Batch processor 
initialization, 
DCL command, 
MCR command, 7-11 
installation, 7-9 to 7-10 
Batch processor prototype task 
See BPR 
Batch queue, 
assignment 
DCL command, 
MCR command, 
BC, 12-27 
BCT, 12-28 
Bit Clear 
See BC 
Bit Clear Test 
See BCT 


5-1, 5-3 


5-3 


5-3 to 5-4 


5-4 


5-1 


4-26 


7-1 


7-11 
7-11 


7-12 


7-13 
7-13 
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Bit Set 

See B 
Bit Set Test 

See BST 
/BLKMOD keyword (VMR), 10-55 
/BOOT keyword (VMR), 10-47 
/BOT keyword (VMR), 10-55 to 

10-56 

BPR, 7-2 
BPR.TSK, 7-10 
/BRO keyword 
BS, 12-27 
BST, 12-28 
/BUF keyword 
Buffer space 

statistics 

with PARAMETERLIST, 4-44 

BUFFERSIZE command 

IOX, 4-27 
BUILD command, 15-7 


(VMR), 10-56 


(VMR), 10-57 


CAN 
See CANCEL command (VMR) 
CANCEL command (VMR), 10-11 
definition, 10-11 
example, 10-11 
format, 10-11 
parameter, 10-11 
Card Reader Spooling Transaction 
Block, 17-31 
CBM, 12-29 
Checkpoint 
dynamic common regions, 14-1 
static common regions, 14-1 
tasks, 14-1 
Checkpointable task 
fixing, 10-18 
Checkpointing, 10-22, 10-28 
common, 10-28 
/CKP keyword (VMR), 10-22 
CLEAR command, 15-8 
CLI, 1-3, 11-1, 11-3 
adding to account entry, 2-3 
changing, 2-7 
continuation lines, 
displaying, 2-5, 2-8 
examples, 11-11, 11-16 
FORTRAN, 11-16, 11-20 
MACRO-11, 11-11, 11-15 
Executive directives, 11-3 
in account entry, 2-1 
interaction with system, 11-3 
MCR, 2-3, 11-2 
multi-CLI support, 2-1, 2-3, 
2-7 
prompting, 11-7 to 11-8 
prompts 
CTRL/C, 11-7 
task-exit, 11-8 
See Command Line Interpreter, 
10-23 
serial command processing, 11-8 
system messages to, 11-5 
task names, 11-4 


11-8 


CLI (Cont.) 
writing, 11-2 to 11-3 
CLI dispatcher task, 12-5 
/CLI keyword (VMR), 10-23 
COs,. 3-1 
as pseudo device, 3-l 
attaching, 3-3 
detaching, 3-3 
monitoring status, 3-6 
reading from, 3-3 
redirecting, 3-7 
CODRV, 3-1 
Command (VMR) 
See also VMR commands 
comments in, 10-5 
components of, 10-4 
file specifications, 10-5 
keyword, 10-4 
keyword value, 10-5 
name, 10-4 
parameter, 10-4 
Command format (VMR), 10-4 
Command Language Interpreters, 
1-3 
Command line 
comments, 10-5 
file specifications, 10-5 
format, 10-4 
rejected, 10-94 
Command Line Interpreter 
See CLI 
task, 10-23 
Command syntax (VMR), 10-4 
abbreviating commands, 10-4 
command keywords, 10-4 
command line format, 10-4 
command names, 10-4 
command parameters, 10-4 
entering comments, 10-5 
keyword values, 10-5 
Common 
checkpointing, 10-28 
directive 
fixing, 10-19 
partition, 14-1 
protecting, 10-25 
synchronizing task use, 10-27 
task sharing, 10-27 
unfixing, 10-92 
COMPAREDATA YES/NO command 
IOX, 4-28 
Compatibility mode 
See VAX-11l1 RSX 
CON 
see CONFIGURATION command (VMR) 
command descriptions, 15-7, 
15-30 
error messages, 15-39, 15-41 
format, 15-39 
invoking, 15-4 
indirect command files, 15-4 
CON command summary, 15-5 
CON commands 
BUILD, 15-5, 15-7 


Index-2 


CON commands (Cont.) CONTROL C command 


CLEAR, 15-5 CONTROL C YES/NO command 
DISPLAY, 15-5, 15-9 IOX, 4-32 
ESTATUS, 15-5, 15-12 IOX 
HELP, 15-5, 15-14 effect on CTRL/C, 4-32 
IDENT, 15-5, 15-15 - CONTROL P 
LINK, 15-5, 15-16 See CTRL/P 
LIST, 15-5, 15-17 Controller failures, 15-34 
OFFLINE, 15-5, 15-19 COP, 12-30 
OFFLINE MEMORY, 15-22 COPY command, 9-7 
ONLINE, 15-6, 15-23 COT..., 3-1 
ONLINE MEMORY, 15-26 Crash Recovery Transaction Block, 
SET, 15-6, 15-27 17-25 
SWITCH, 15-6, 15-29 Create option 
UNLINK, 15-6, 15-30 ACNT, 2-3 
Configuration /CRT keyword (VMR), 10-57 
of devices in IOX, 4-29 /CTB keyword (VMR), 10-33 
CONFIGURATION command (VMR), CTRL/C command 
10-12 See CONTROL C command, 4-32 
definition, 10-12 CTRL/P, 9-3, 9-7 


examples, 10-13, 10-16 
formats, 10-12 


keywords Data terminal emulation 
CONTROLLERS, 10-13 See DTE, 9-1 
CPU, 10-13 Data Terminal Emulator 
FULL, 10-13 See DTE 
UNITS, 10-13 see DTE 

parameters, 10-12 Date 

CONFIGURE command displaying, 10-90 
IOX, 4-29 setting, 10-90 


Console Logger, 1-1, 3-1 DCL, 11-2, 11-5, 11-8 
communication with, 3-2 building, 12-1 
task communication, 3-2 conventional installation, 12-2 
user communication, 3-2 deleting files, 9-7 


Console Logging IFORM, 12-24 
Co: installation, 12-1 
writing to, 3-2 alternatives, 12-2 
commands, 3-3 catchall task, 12-3 
error messages, 3-l1l MCR task, 12-3 
installing COT..., 3-2 intermediate form 
loading CODRV, 3-2 See IFORM 
log file MCR fallthrough, 12-4 
disabling, 3-5 parser process, 12-5 
reassigning, 3-5 parser table example, 12-21 
multiple commands, 3-6 SET commands, 12-3 
reading log file, 3-8 task, 12-3 
sample session, 3-8 task building, 12-4 
starting, 3-4 task-building 
stopping, 3-4 first task build, 12-4 
Console Output Device second task build, 12-5 
See CO:, 3-1 telephone number 
Console terminal specifying, 9-4 
disabling, 3-5 terminal emulation 
display, 3-4 specifying, 9-3, 9-5 
reassigning, 3-5 transferring files, 9-7 
Continuation line translator process, 12-5 
CLI, 11-8 DCL command table, 12-7 
CONTINUE command constructing, 12-6 
Shadow Recording, 18-8 example, 12-46, 12-48 
Contradictory Bit Mask interpreting, 12-18 
See CBM, 12-29 modifying, 12-8 
Control. DCL commands 
IOX command interpretation, 12-5 
category, 4-3 mapping to MCR, 12-21 
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DCL Master Command Table 
See DCL MCT 
DCL MCT, 12-9 
DCL QMG commands 
DCL task, 1-4, 12-5 
adding commands, 
definition, 12-1 
deleting commands, 
modifying commands, 
overlay, 12-10 
PT/TT, 12-12 
file, 12-9 
Deallocate Device Transaction 
Block, 17-28 
/DEC keyword (VMR), 10-57 
DECnet Remote Terminal Facility 
See RMT 
DECtape 
exercising 
IOX, 4-2 
Default (VMR) 
device, 10-5 
directory, 10-6 
file name, 10-6 
file types, 10-6 
version number, 10-6 
DELETE command, 9-7 
Delete option 
ACNT, 2-9 
DELETE/REMOTE command, 9-7 
/DENS keyword (VMR), 10-48 
Density 
tape 
in IOX, 4-33 
DENSITY command 
IOX, 4-33 
DESELECT command 
IOX, 4-35 
Despool prototype task 
See LPP 
DEV 
See DEVICES command 
DEV command 
disk data caching, 
Device 
exercising 
examples 
RLO2, 


12-8 


12-13 
12-13 


(VMR) 


19-15 


4-10 
IOX 
adding, 4-29 
displaying, 
exercising 
steps, 4-2 
status during exercise, 4-6 
testing 
removing, 
time of, 
null, 10-39 
offline, 10-17 
placing off line, 
Placing on line, 
pseudo, 10-3 
redirecting, 10-39 
redirecting restrictions, 


4-29 


4-35 


4-57 


15-3 
15-3 


10- 


Device (Cont.) 
removing, 10-93 
removing attached device, 10-93 
system default 
adding to account entry, 
changing, 2-7 
displaying, 2-5, 2-8 
in account entry, 2-1 
Device context, 15-3 
Device Statistics Block, 
Device statistics example 
Resource Accounting, 17-7 
Device unit failures, 15-34 
DEVICES command (VMR), 10-16 
definition, 10-16 
example, 10-16 
format, 10-16 
notes, 10-17 
parameter, 10-16 
Diagnostic error message, 
Diagnostics Loader task 
See DLD 
Digital Command Language 
See DCL 
task, 12-1 
DIR attribute, 12-31 
/DIR keyword (VMR), 
Disk 
block 
random or sequential 
IOX, 4-51 
testing range display 
IOX, 4-52 
testing range for NFS volumes 
IOX, 4-52 
exercising 
examples 
RLO2 
IOX, 
IOX, 4-2 
exercising 
examples 
NFS volume, 
Files-1l 
parameter commands 
IOX, 4-8 
testing 
IOX, 
testing 
selecting random testing 
IOxX, 4-51 
skipping blocks 
IOX, 4-41 
Disk Data Caching, 
Data Cache Manager, 
DCL commands, 19-6, 
features, 19-1 
I/O operations, 19-1 
including in system, 
MCR commands, 19-10, 
options, 19-7, 19-10 
region, 19-3 
Dismount Device Transaction Block, 
17-29 


2-3 


17-31 


10-94 


10-19 


4-10 
(10x) 


4-15 


4-63 


0 1-5, 19-1 
19-3 


19-10 


19-1, 19-3 


19-16 


39 
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Display 
IOX 
bad blocks list, 4-26 
commands as a category, 4-3 
continuing 
with PROCEED, 4-50 
status during exercise, 4-60 
DISPLAY command, 15-9 
Shadow Recording, 18-9 
DLD, 15-36 
how to use, 15-36, 15-39 
DMAP attribute, 12-32 
DTE, 1-3, 9-1 
Dynamic common region 
checkpointing, 14-3 
shuffling, 14-6 


/EBC keyword (VMR), 10-57 
/ECHO keyword (VMR), 10-58 
Echo loops, 9-4 
/EDIT keyword (VMR), 10-58 
ERR attribute, 12-31 
Error limit 
altering 
IOX, 4-36 
Error Logger, 15-32 
Error message format, 10-94 
Error messages 
IOX, 4-68 
Error messages (VMR), 10-94, 
10-112 
diagnostic, 10-94 
fatal, 10-94 
format, 10-94 
unmarked, 10-94 
Error report 
data compare 
IOX, 4-21 
directing to device 
IOX, 4-42 
disabling 
IOX, 4-54 
enabling 
IOX, 4-54 
I/O error 
IOX, 4-22 
types 
IOX, 4-54 
ERRORLIMIT command 
IOX, 4-36 
ESCAPE key 
requesting list of options 
ACNT, 2-3 
/ESCSEQ keyword (VMR), 10-58 
ESTATUS command, 15-12 
Event flag 
IOX, 4-66 
Examine option 
ACNT, 2-5 
EXECUTE command 
IOX, 4-37 
Execution 
termination of task 
IOX, 4-24 


Execution mode 
entering 
IOX, 4-61 
IOX, 4-18 
Executive data space support, 
10-3 
Executive pool monitor code, 13-1 
EXIT command 
IOX, 4-38 
Exit option 
ACNT, 2-11 


Fast-mapping, 10-23 
Fatal error message, 10-94 
Fault isolation, 15-33 
/EDX keyword (VMR), 10-59 
File 
See also Account file 
copying 
See also File transferring 
transferring, 9-1, 9-3, 9-5, 
9-8 
Professional Personal 
Computer systems, 9-1 
VAX-11 RSX systems, 9-1, 9-5 
File size 
specifying in blocks, 4-63 
File specification (VMR) 
components, 10-5 
defaults, 10-5 
device name, 10-5 
directory, 10-6 
file name, 10-6 
file type, 10-6 
format, 10-5 
/IM switch, 10-7 
named directory, 10-6 
specifying, 10-5 
version number, 10-6 
File-structured device 
exercising 
IOX, 4-3 
Files-11 
disk 
selecting for testing 
IOX, 4-39, 4-65 
volume 
protecting with TEMPORARYFILE 
IOX, 4-63 
volume exercise 
example 
IOX, 4-10 
Files-11 volume 
selecting, 4-7 
FILES11 command 
IOX 
default parameters, 4-39 
FIX command (VMR), 10-18 
definition, 10-18 
examples, 10-19 
format, 10-18 
keywords 
/DIR, 10-19 
/NSF, 10-19 
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FIX command 
keywords 
/REG, 10-19 
/RON, 10-19 
parameter, 10-18 
/EIX keyword (VMR), 10-23 
FIX-IN-MEMORY command 
See FIX command (VMR) 
Fixing 
directive common, 10-19 
Flying installs, 12-4 
/EMAP keyword (VMR), 10-23 
/FORMFEED keyword (VMR), 10-59 
Full-duplex terminal driver, 
10-50 


(VMR ) 
(Cont. ) 


GET/SET option, 10-50 
Function commands 

IOX category, 4-3 
/GBL keyword (VMR), 10-10 
Hard errors, 15-32 
Hardware faults, 15-31 


intermittent failures, 15-32 
media failures, 15-31 
transient failures, 15-31 

HELP command, 15-14 
IOX, 4-40 

/HFILL keyword (VMR), 10-59 

/HHT keyword (VMR), 10-59 

High pool, 13-3 to 13-4 

High pool event, 13-2 

HLP attribute, 12-32 

HRC, 15-2 
error messages 

format, 15-39 

HRC error messages, 

/HSYNC keyword 


15-41, 
(VMR), 10-60 


15-44 


I/O error report 
IOX, 4-22 

I/O exercise 
steps, 4-2 
termination, 

I/O Exerciser 
See IOX 

I/O Queue Optimization, 1-5, 
Cylinder Scan, 16-1, 16-4 
default, 16-3 
Elevator, 16-1 
Elevator Method, 
error messages, 
fairness count 

adjustment, 16-3 

Fairnesscount, 16-1 
initiating, 16-1 
Nearest Cylinder, 


4-24 


16-1 


16-4 
16-4 


16-1, 16-4 


optimization status, 16-2 
optimization types, 16-1 
selecting method, 16-3 

IDENT command, 15-15 

IFORM, 12-24 

/IM switch (VMR) 
definition, 10-7, 10-47 


/I1OP keyword 


/IM switch (VMR) (Cont.) 
relationship to symbol 
definition file, 10-7 
uses, 10-7 
7INC keyword (VMR), 10-24 
Indirect command file 
IOX, 4-6 
Indirect Command File (VMR), 
levels allowed, 10-4 
specifying, 10-4 
VMR requirements, 
INS 
See INSTALL command 
INSTALL command (VMR), 
definition, 10-21 
examples, 10-30 to 10-31 
format, 10-21 
keywords 
/REF, 
/CKP, 
/GL1, 
/EIX, 
/EMAP, 
/INC, 
/IOP, 
/PMD, 
/PRI, 
/PRO, 


10-3 


(VMR) 
10-21 


10-22, 
10-22 
10-23 
10-23 
10-23 
10-24 
10-24 
10-25 
10-25 
10-25 
/RON, 10-26 
/ROPAR, 10-26 
/SEC, 10-27 
/SLV, 10-27 
/SYNC, 10-27 
/TASK, 10-27 
/UIC, 10-28 
/WB, 10-28 
/XHR, 10-28 
notes, 10-31 to 10-32 
parameters, 10-21 
Interactive mode 
IOxX, 4-19 
INTERLEAVE command 
IOX, 4-41 
Intermittent failures, 
Interval report 
IOX, 4-20 


10-25 


15-32 


10-3 


Invalid Login Transaction Block, 


17-27 
(VMR), 10-24 
IOxX, 1-1 
command 
LOOPBACK, 4-43 
parameter list 
for Files-ll, 
command mode, 4-18 
commands 
ABORT, 4-24 
BADBLOCKS, 
BUFFERSIZE, 4-27 
categories, 4-3 
COMPAREDATA YES/NO, 
CONFIGURE, 4-29 
CONTROL C YES/NO, 4-32 
CTRL/C, 4-31 


4-8 


4-25 


4-28 
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IOx IOx (Cont.) 


commands (Cont.) file-structured exercising, 4-3 
DENSITY, 4-33 increment, 4-5 
descriptions, 4-22 indirect command files, 4-6 
DESELECT, 4-35 installation 
ERRORLIMIT, 4-36 ‘ on RSX-11M, 4-4 
EXECUTE, 4-37 on RSX-11M-PLUS, 4-4 
EXIT, 4-38 interleaving with Executive, 
files, 4-6 4-66 
FILES11, 4-39 interval report output 
HELP, 4-40 frequency, 4-62 
in interactive mode, 4-19 invoking 
INTERLEAVE, 4-41 on RSX-11M, 4-5 
LOGFILE, 4-42 on RSX-11M-PLUS, 4-5 
parameter when installed, 4-5 
by device type, 4-9 when not installed, 4-5 
with FILES11, 4-8 with an increment, 4-5 
with SELECT, 4-9 without an increment, 4-5 
with VERIFY, 4-9 nonfile-structured exercising, 
parameter list 4-3 
for NFS volumes, 4-9 output type 
PARAMETERLIST, 4-44 activity report, 4-20 
PATTERN, 4-48 interval report, 4-20 
PRINTSUMMARY, 4-49 summary report, 4-20 
PROCEED, 4-50 parameter 
RANDOM, 4-51 command exercising magnetic 
RANGE, 4-52 tape, 4-12 
RECORDS, 4-53 exercising 
REPORTERRORS YES/NO, 4-54 device-dependent exercise, 
RESTART, 4-55 4-8 
RETRIES, 4-56 Files-l1 volumes, 4-10 
RUNTIME, 4-57 NFS volume, 4-15 
SELECT, 4-58 general list of exercise 
SPY, 4-60 parameters, 4-8 
START, 4-61 overriding default 
SUMMARYTIME, 4-62 FILES11, 4-39 
syntax, 4-22 SELECT, 4-58 
TEMPORARYFILE, 4-63 showing default with 
VERIFY, 4-64 PARAMETERLIST, 4-44 
VOLUMECHECK, 4-65 parameter command category, 4-3 
WAIT, 4-66 pattern 
WRITECHECK, 4-67 altering test, 4-48 
considerations for, 4-1 displaying test, 4-48 
controlling with CTRL/C, 4-32 restarting, 4-55 
data running steps, 4-1 
compare error report, 4-21 selecting 
pattern checking, 4-28 NFS volume, 4-8 
transfer size of, 4-27 starting, 4-61 
DECtape exercising, 4-2 task termination, 4-18 
defaults task-build file 
changing during task build, location of, 4-22 
4-22 termination, 4-38 
device using PROCEED, 4-50 
exercising steps, 4-2 test configuration, 4-29 
status display, 4-60 adding units, 4-6 
testing displaying, 4-6 
time of, 4-57 setting up, 4-6 
disk exercising, 4-2 testing 
error messages, 4-68 removing devices from, 4-35 
execution mode, 4-18 wait-for-event flag, 4-66 
entering, 4-18 write-check, 4-67 
exercise parameters 
general list, 4-8 LBN, 5-2 
exiting, 4-38 /LIBUIC keyword (VMR), 10-60 
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/LINES keyword (VMR), 10-61 
LINK command, 15-16 
LIST command, 15-17 
List option 
ACNT, 2-8 
LOA 
See LOAD command (VMR) 
LOAD command (VMR), 10-33 
definition, 10-33 
examples, 10-34 
format, 10-33 
keywords 
/CTB, 10-33 
/PAR, 10-33 
/SIZE, 10-34 
/VEC, 10-34 
notes, 10-34 
parameters, 10-33 
LOGFILE YES/NO command 
IOX, 4-42 
Logical AND, 12-27 
Logical Block Number, 10-31 
Logical blocks 
See LBN 
LOGICAL UNIT NUMBERS command 
See LUNS command (VMR) 
LOGIN command, 9-6 
Login Transaction Block, 17-30 
/LOGON keyword (VMR), 10-61 
LOGOUT command, 9-3, 9-7 
LOOPBACK 
parameter command, 4-43 
Low pool, 13-3 to 13-4 
Low pool event, 13-2 
/LOWER keyword (VMR), 10-61 
LPP, 7-2 
LUN 
See LUNS command (VMR) 
LUNS command (VMR), 10-35 
definition, 10-35 
example, 10-35 
format, 10-35 
parameter, 10-35 


Macro Metalanguage 
See MML 
Magnetic tape 
density 
displaying in I0X, 4-33 
specifying in IOX, 4-33 
error retries, 4-56 
exercise 
example, 4-12 
using SELECT, 4-12 
records tested, 4-53 
testing 


altering record count, 4-53 
/MAIN keyword (VMR), 10-61, 10-63 


MAP attribute 

secondary mappings, 12-35 
MAP attributes, 12-33 to 12-34 
Master Command Table 

See MCT 
/MAXEXT keyword (VMR), 10-63 


MCR, ll-1l to 11-2 
CLI default, 2-3 
transferring files, 9-5, 9-7 
translator table example, 12-21 
MCR CLI command, 11-5 
MCR command, 12-3 
MCR QMG commands 
MCR UFDs, B-3T 
MCT 
contents, 12-7 
Media failures, 15-31 
Memory, 14-1 
compacting space 
See SHF 
Memory management 
fixing tasks, 10-18, 10-23 
Metalanguage, 12-13 
category references, 12-14 
exclusive-OR, 12-15 
optional syntax indicators, 
12-15 
production rule, 12-14 
adjective, 12-14 
subject, 12-14 
syntax tree, 12-14 
MFT, 9-1 
MFT command, 9-5, 9-7 
Micro/RSX File Transfer Utility 
See MFT 
MK11 memory box failures, 15-35 
MML, 12-16 
features, 12-6 to 12-7 
literals, 12-20 
nonliterals, 12-19 
parser functions, 12-20 
handling of literals, 12-20 
handling of nonliterals, 
12-19 
translator functions, 12-20 
handling of literals, 12-20 
handling of nonliterals, 
12-19 
Modify option 
ACNT, 2-7 
Monitor Console Routine 
See MCR 
Mount Device Transaction Block, 
17-28 
MOUNT/CACHE command 
disk data caching, 19-6, 19-10 
MSCP disks 
configuration, 5-2 
Multistream line printer spooling, 
7-1 
Mutiprocessor systems 
stand-alone maintenance, 15-36 


/NETUIC keyword (VMR), 10-63 
NES 
exercise example, 4-15 
testing range of blocks, 4-52 
volume 
altering range of test blocks, 
4-52 
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NFS 
volume (Cont.) 
displaying range of test 
blocks, 4-52 
error retries, 4-56 
selecting with SELECT, 4-58 
selecting with VERIFY, 4-64 
NFS volume 
selecting 
with VERIFY, 4-8 
NO attribute, 12-36 
Non-file-structured exercising 
IOX, 4-3 
Nonrecoverable errors, 15-32 
/NSF keyword (VMR), 10-19 
Null device, 10-39 


OCOP, 12-30 
ODT 
disabling, 9-4 
OFFLINE command, 15-19 
OFFLINE MEMORY, 15-22 
On-Line Debugging Tool 
See ODT 
ONLINE command, 15-23 
ONLINE MEMORY, 15-26 
/OPT keyword (VMR), 10-64 


PAR 
See PARTITIONS command (VMR) 
/PAR keyword (VMR), 10-33, 10-64, 


10-66 
Parameter 
IOX 
command category, 4-3 
exercising 
device-dependent exercise, 


4-8 
Files-1l1 volumes, 4-10 
Magnetic tape, 4-12 
NFS volume, 4-15 
list of exercise parameters, 
4-8 
overriding default 
FILES11, 4-39 
SELECT, 4-58 
showing default with 
PARAMETERLIST, 4-44 
PARAMETERLIST command 
IOX, 4-44 
displaying buffer space, 4-44 
displaying defaults, 4-44 
Parameters (VMR), 10-4 
/PARITY keyword (VMR), 10-66 to 
10-67 
Parser processing, 12-19 
Partition 
common, 14-1 
common block, 10-31 
creating, 10-54 
definition, 14-1 
fragmentation, 14-3 
main, 19-4 
modifying, 10-55 


Partition (Cont.) 
overriding, 10-24 
region, 10-18 
system-controlled, 14-1 
type, 10-65 
user-controlled, 14-1 
PARTITION command (VMR), 10-36 
definition, 10-36 
example, 10-36 
format, 10-36 
PARTITION DEFINITIONS command 
See PARTITIONS command (VMR) 
Partition display 
contents, 10-36 
symbol meaning, 10-36 
Password 
adding to account entry, 2-3 
changing, 2-1, 2-7 
characters, 2-3 
contained in account entry, 2-1 
displaying, 2-5, 2-8 
/PASTHRU keyword (VMR), 10-67 
Pattern 
IOX 
altering test, 4-48 
displaying test, 4-48 
PATTERN command 
IOX, 4-48 
Peripheral Interchange Program 
See PIP utility 
PIP utility 
account file 
copying, 2-3 
extending, 2-3 
PLAS 
fixing tasks, 10-23 
/PLCTL keyword (VMR), 10-68 
/PMD keyword (VMR), 10-25 
PMT, 1-4 
abortable tasks, 13-7 
aborting, 13-11 to 13-12 
action, 13-11 
activation, 13-3 
conditions affecting, 13-3 
controlling pool use, 13-11 
defaults 
extreme fragmentation, 13-6 
high pool state, 13-5 
low pool state, 13-5 
functions, 13-3 
installation, 13-3 
messages, 13-8 
output 
example of extreme 
fragmentation, 13-9 to 
13-10 
low pool state, 13-6 
task-build options, 13-10 
timing, 13-10 
Pool 
conditions, 13-2 
largest fragment increases, 
13-5 
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Pool 
conditions (Cont.) 
largest fragment too small, 
fragmentation, 
pool 
definition, 13-1 
Pool fragment size, 
/POOL keyword (VMR), 
Pool limits, 13-12 
high, 13-12 
low, 13-12 
Pool Monitor Task 
See PMT 
See PMT, 13-1 
Pool monitoring interface 
functions, 13-2 
Pool Monitoring Support, 
receiving, 13-1 
/POOLSIZE keyword (VMR), 10-69 
Predefined syntax elements, 12-40 


13-1 


13-13 
10-69 


1-4 


basic data types, 12-40 to 
12-41 

common command elements, 12-42 
to 12-43 

program control elements, 12-46 

special parser elements, 12-43, 


special translator elements, 
12-45 to 12-46 
/PRI keyword (VMR), 
Primary RBNs, 5-4 
Print Despooler Transaction Block, 
17-30 
print processors 
installation 
DCL command, 
MCR command, 
print queue. 
initialization 
DCL command, 7-5 
MCR command, 7-5 
/PRINTER PORT keyword 
10-69 
PRINTSUMMARY command 
IOX, 4-49 
/PRIV keyword (VMR), 
Privileged user input 
rejection of, 10-50 
PRO attribute, 12-37 
/PRO keyword (VMR), 
PROCEED command 
IOX, 4-50 
Processor failures, 15-34 
Professional Personal Computer 


10-8, 10-25 


7-6 
7-6 


(VMR) , 


10-70 


10-25 


file transfer, 9-1 
Prompting 

CLI, 11-7 to 11-8 
Protection 

file, 2-3 
Protection mask, 10-25 
Protection UIC, 10-25 


Prototype task 
fixing, 10-18 


10-27 
A-2 


Prototype tasks, 
PRT error messages, 
PRT task, 1-6 
PRI 6 ace 

See Serial Despooler Task 
Pseudo device 

installing from, 
/PUB keyword (VMR), 


10-3 
10-70 


QMG, 1-2, 7-1 
commands, 7-14 
ASSIGN/QUEUE, 7-23 
DCL format, 7-14 
DEASSIGN/QUE, 7-23 
DELETE, 7-21 
DELETE PROCESSOR, 
DELETE/QUEUE, 7-21 
INITIALIZE/PROCESSOR, 
MCR format, 7-14 
START, 7-27 
START/PROCESSOR, 
START/QUEUE, 7-27 
START/QUEUE/MANAGER, 
STOP, 7-24 
STOP/ABORT, 7-26 
STOP/PROCESSOR, 
STOP/QUEUE, 7-24 
STOP/QUEUE/MANAGER, 7-24 
INITIALIZE command, 7-14 
INITIALIZE/QUEUE, 7-14 
installation, 7-3, 7-9 
starting, 7-4 
DCL command, 
MCR command, 
QMGCLI, 7-1 
SQTRAN, 17-17 
SQTRAN], 17-18 
SQTRAN2, 17-19 
QUA attribute, 12-38 
Queue management subsystem, 
to 7-2 
Queue Manager, 


7-21 


7-29 


7-25 


7-4 
7-4 


1-2, 7-1 
RANDOM command 
IOX, 4-51 
RANGE command 
IOX, 4-52 
RBNs, 5-2 
primary 
secondary 
status codes, 
RCT, 5-1, 5-5 
See Bad Block Replacement 
Control Task 
and Error Logger, 
installation, 5-2 
RD:, 15-1 
REA 
See REASSIGN command 
Read 
nondestructive 
NFS volumes, 4-64 
REASSIGN command (VMR), 
definition, 10-38 


5-2 to 5-3 


5-5 


(VMR ) 
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7-16 


7-27 


10-38 


REASSIGN command (VMR) 
examples, 10-38 
format, 10-38 
parameters, 10-38 

Reconfiguration components, 15-1 
CON, 15-1 
HRC, 15-1 
RD:, 15-1 = 

Reconfiguration driver 
See RD: 

Reconfiguration services, 1-4, 

15-1 
initiating, 15-4 
system faults, 15-31 

Reconfiguration task 
See HRC 

RECORDS command 
IOX, 4-53 

Recoverable errors, 15-32 

RED 
See REDIRECT command (VMR) 

REDIRECT command (VMR), 10-39 
definition, 10-39 
examples, 10-39 
format, 10-39 
parameters, 10-39 
restrictions, 10-39 

/REG keyword (VMR), 10-19, 10-40, 

10-92 
Region 
disk data cache, 19-3 
extent, 19-3 
format, 19-4 
dynamic storage, 10-69 
fixing, 10-19 
read-only, 10-26 
read/write access, 10-26 
unfixing, 10-92 

/REGIS keyword (VMR), 10-70 

REM 
See REMOVE command (VMR) 

/REMOTE keyword (VMR), 10-71 to 

10-72 

REMOVE command (VMR), 10-40 
definition, 10-40 
examples, 10-40 
format, 10-40 
keyword 

/REG, 10-40 
notes, 10-40 
parameters, 10-40 

Replacement blocks 
See RBNs 

Report 
interval 

output frequency, 4-62 

REPORTERRORS YES/NO command 
IOX, 4-54 

Reschedule interval, 10-43 

Resource Accounting, 1-5, 17-1 
See also Transaction file 
commands, 17-4 

SET ACCOUNTING, 17-4, 17-8 


(Cont.) 


Resource Accounting 
commands (Cont.) 
SHOW ACCOUNTING/DATATRIEVE, 
17-3, 17-17 
SHOW ACCOUNTING/INFORMATION, 
17-3, 17-11 


SHOW ACCOUNTING/TRANSACTION FILE, 


17-3, 17-12 
START/ACCOUNTING, 17-4 to 
17-5 
STOP/ACCOUNTING, 17-4, 17-10 
device statistics example, 17-7 
interface for creating 
transactions 
SQTRAN, 17-17 
SQTRAN1, 17-18 
SQTRAN2, 17-19 
messages, 17-40 
privileged task interface, 
17-21 
scan rate, 17-6 
secondary pool, 17-5 
statistics scan, 17-6 
system resources, 17-39 
system statistics, 17-5 
task accounting, 17-6 
user-written analysis programs, 
17-3 
using DATATRIEVE-11 for an 
accounting report, 17-16 
Resource Monitoring Display 
See RMD 
RESTART command 
IOX, 4-55 
RETRIES command 
IOX, 4-56 


- Revector control tables, 5-2 


RLO2 exercise 
IOX, 4-10 
RMD, 1-2, 6-1 
Active Task Display, 6-8 
altering 
from MCR, 6-9 
altering from setup page, 6-8 
Active Task List Page, 6-1 
cache region 
detailed statistics 
altering from MCR, 6-18 
detailed statistics display, 
6-16 
altering from setup page, 
6-17 
general statistics 
altering from MCR, 6-16 
general statistics display, 
6-14 
altering from setup page, 
6-15 
General Statistics Page, 6-1 
cached device 
Detailed Statistics Page, 6-1 
display pages, 6-1 
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RMD 
displaying 
disk data cache statistics, 
19-14 
displaying disk data cache 
statistics, 19-12 
displays available on 
RSX-11IM-PLUS, 6-11 
error messages, 6-18 
Help display, 6-3 
Help Page, 6-1 
I/O Counts Display 
altering 
from MCR, 6-12 
from setup page, 6-12 
I/O Counts Page, 6-1 
installation, 6-2 
MCR INSTALL command, 6-2 
RSX-11M systems, 6-2 
RSX-11M-PLUS systems, 6-2 
invoking, 6-2 
memory display, 6-4 
FREE command, 6-7 
modifying, 6-7 
RATE command, 6-7 
Memory Page, 6-1 


pages, 6-1 
running on a slaved terminal, 
6-3 


setup command, 6-2 
setup pages, 6-2 
System Statistics Display, 6-13 
altering 
from MCR, 6-14 
from setup page, 6-14 
System Statistics Page, 6-1 
Task Header Display, 6-9 
altering 
from MCR, 6-11 
from setup page, 6-10 
contents, 6-10 
Task Header Page, 6-1 
task-build command file 
altering, 6-18 
using at terminals, 6-2 
RMT, 11-2 
/RNDC keyword (VMR), 10-72 
/RNDH keyword (VMR), 10-72 
/RNDL keyword (VMR), 10-72 
/RON keyword (VMR), 10-19, 10-26, 
10-92 
/ROPAR keyword 
/RPA keyword 
/RSI keyword 
RSX11.SYS 
See Account file 
RUN command (VMR), 10-42 
definition, 10-42 
formats, 10-42, 10-46 
keywords 
/RSI, 10-44 
/UIC, 10-44 
parameters, 10-42 
restriction, 10-42 


(VMR), 10-26 
(VMR), 10-73 
(VMR), 10-44 


RUN command (VMR) (Cont.) 
time options, 10-42 
Running VMR, 10-2 
RUNTIME command 
IOX, 4-57 


SAB 
Resource Accounting, 17-11 
Sample configuration 
increasing system throughput, 
15-20 
SAV 
See SAVE command (VMR) 
SAVE command (VMR), 10-47 
definition, 10-47 
example, 10-48 
format, 10-47 
keywords 
/BOOT, 10-47 
/DENS, 10-48 
notes, 10-48 
parameters, 10-47 
Scan rate 
Resource Accounting, 17-6 
/SEC keyword (VMR), 10-27 
Secondary pool 
Resource Accounting, 17-5 
Secondary RBNs, 5-4 
/SECPOL keyword (VMR), 10-73 
SELECT command 
IOX, 4-58 
Serial command processing 
CLI, 11-8 
Serial Despooler 
See PRT 
Serial Despooler Task 
error messages, A-2 
receive queue operation, A-1l 
task-build information, A-1l 
text requirements, A-1l 
/SERIAL keyword (VMR), 10-73 
SET /PLCTL command, 13-12 
SET ACCOUNTING 
Resource Accounting, 17-4 
Set Accounting Transaction Block, 
17-26 
SET command, 15-27 
disk data caching, 19-16 
I/O Queue Optimization, 16-1 
SET command (VMR), 10-50 > 
definition, 10-50 
examples, 10-83, 10-87 
Executive features, 10-50 
format, 10-50 
keyword table, 10-51, 10-53 
keywords 
/AFF, 10-54 
/BOT, 10-55 to 10-56 
/BUF, 10-57 
/HFILL, 10-59 
/LIBUIC, 10-60 
/LINES, 10-61 
/MAXEXT, 10-63 
/NETUIC, 10-63 
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SET command (VMR) 
keywords (Cont.) 

/{NO]ABAUD, 10-53 
/([NOJANSI, 10-54 
/{NO]JAVO, 10-54 
7 {NO]BLKMOD, 10-55 
/(NO]BRO, 10-56 
/(NOJCRT, 10-57 
/(NO]DEC, 10-57 
/(NOJEBC, 10-57 
/ ([NO]ECHO, 10-58 
/(NOJEDIT, 10-58 
/ [NO]ESCSEQ, 10-58 
/{NO]FDX, 10-59 
/{NO]FORMFEED, 10-59 
/(NO]HHT, 10-59 
/{NO]HSYNC, 10-60 
/{NO]LOGON, 10-61 
/(NO]LOWER, 10-61 
/(NO]MAIN, 10-61, 10-63 
/{NO]OPT, 10-64 
/(NO]PAR, 10-64, 10-66 


/({NO] PARITY, 10-66 to 10-67 


/{NO]PASTHRU, 10-67 

/ [NO]PRINTER PORT, 10-69 
/(NO]PRIV, 10-70 
/(NO]PUB, 10-70 
/{NO]REGIS, 10-70 


/{NO]REMOTE, 10-71 to 10-72 


/{NO]RPA, 10-73 
7 (NO]SERIAL, 10-73 
/(NO]SLAVE, 10-74 
/(NO]SOFT, 10-74 
/({NO]SUB, 10-76 to 10-77 
/{NO]JTTSYNC, 10-80 
/(NO]TYPEAHEAD, 10-80 to 
10-81 

/{NO]VFILL, 10-81 
/ [NO]WCHK, 10-81 
/{NO]JWRAP, 10-82 to 10-83 
/PLCTL, 10-68 
/POOL, 10-69 
/POOLSIZE, 10-69 
/RNDC, 10-72 
/RNDH, 10-72 
/RNDL, 10-72 
/SECPOL, 10-73 
/SPEED, 10-75 
/SWPC, 10-77 
/SWPR, 10-77 
/SYSUIC, 10-77 
/TERM, 10-78 to 10-79 
/TOP, 10-79 to 10-80 
/UIC, 10-81 

parameter, 10-51 

uses, 10-50 


SET HOST/DTE command, 9-3, 9-5 to 


9-6 
SET PASSWORD, 2-1 
SET TERMINAL command, 9-3 
Shadow Recording, 1-5 
Bad block handling, 18-10 
commands, 18-4 
ABORT, 18-4, 18-7 


Shadow Recording 

commands (Cont.) 
CONTINUE, 18-4, 18-8 
DISPLAY, 18-4, 18-9 
START, 18-4 to 18-5 
STOP, 18-4, 18-6 

controlling, 18-4 

error messages, 18-11 

preparation, 18-2 

primary disk errors, 18-10 

secondary disk errors, 18-10 


simultaneous disk errors, 18-1ll 


uses, 18-1 
SHF, 1-4 
algorithms 
first pass, 14-5 
second pass, 14-6 
conventions, 14-1 
installation, 14-4 
monitoring with RMD, 14-4 
overhead, 14-4 
performance, 14-4 
removal, 14-5 
shuffling 


dynamic common regions, 14-5 


fixed tasks, 14-5 
partition sections, 14-5 
static common regions, 14-5 
size, 14-4 
SSHFCT 
changing contents, 14-4 
SSHFTM, 14-4 
SHOW ACCOUNTING commands, 17-11 
SHOW ACCOUNTING/INFORMATION 
Resource Accounting, 17-3 


SHOW ACCOUNTING/TRANSACTION FILE 


Resource Accounting, 17-3 
SHOW CACHE command 
disk data caching, 19-8 
SHOW DEVICE command 
disk data caching, 19-9 
Shuffler 
See SHF 
Shutdown 
RSX-11M system 
example, 8-5 
procedure, 8-4 
RSX-1L1IM-PLUS system 
example, 8-7 
' procedure, 8-6 
SHUTUP 
examples 
RSX-11M, 8-2 
RSX-1LIM-PLUS, 8-2 
input, 8-2 
invoking, 8-1 
output, 8-2 
prerequisites to running, 8-l 
SHUTUP program, 1-3, 8-1 
SHUTUP.CMD, 8-3 
example of file, 8-4 
/SIZE keyword (VMR), 10-34 
/SL switch (TKB), 10-27 
/SLAVE keyword (VMR), 10-74 
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/SLV_ (VMR) 
and /SL switch (TKB), 10-27 
and prototype tasks, 10-27 
/SLV keyword (VMR), 10-27 
Soft errors, 15-32 
/SOFT keyword (VMR), 10-74 
Sort option 
ACNT, 2-10 
/SPEED keyword 
SPWNS directive 
IOX 
in EXECUTE command, 4-37 
SPY command 
IOX, 4-60 
START command 
IOX, 4-61 
Shadow Recording, 18-5 
START/ACCOUNTING 
Resource Accounting, 17-5 
Starting VMR, 10-2 
STARTUP.CMD, 7-1 
Static common region 
checkpointing, 14-3 
resident common, 14-3 
resident libraries, 14-3 
shuffling, 14-6 
Statistics scan 
Resource Accounting, 17-6 
STOP command 
Shadow Recording, 18-6 
STOP/ACCOUNTING 
Resource Accounting, 17-4 
/SUB keyword (VMR), 10-76 to 
10-77 
Summary report 
generated by PRINTSUMMARY, 4-49 
IOX, 4-20 
SUMMARYTIME command 
IOX, 4-62 
SWITCH command, 15-29 
/SWPC keyword (VMR), 10-77 
/SWPR keyword (VMR), 10-77 
Symbol Definition File 
/IM switch, 10-2 
relationship to system image 
file, 10-1 
specifying, 10-2 
VMR requirements, 10-1 
/SYNC keyword (VMR), 10-27 
Syntax elements 
attributes, 12-26 
System Account Block, 17-3, 17-24 
System device 
states, 15-2 
System faults, 15-31, 15-33 
System file names 
conventions, B-4 
System File Types, B-5T to B-6T 
System Image File 
assigning SY: and LB:, 10-1 
bootstrap, 10-1 
relationship to symbol 
definition file, 10-1 
VMR prompt, 10-3 


(VMR), 10-75 


System Image File (Cont.) 
creating, 10-18 
size, 10-18 
/SYSTEM keyword (VMR), 10-10 
System reconfiguration, 15-1 
System recovery, 15-33 
methods, 15-33 
System statistics 
Resource Accounting, 17-5 
System Task Directory, 10-31 
System Time Change Transaction 
Block, 17-29 
System UFDs, B-3T to B-4T 
example, B-3 
System-controlled partition, 14-1 
conventions, 14-3 
definition, 14-3 
fragmentation 
causes of, 14-4 
subpartitions of, 14-3 
waiting tasks, 14-3 
/SYSUIC keyword (VMR), 10-77 


TAB 
Resource Accounting, 17-11 
TAS 
See TASKLIST command 
Task 
access to commons, 10-25 
after exit, 10-92 
checkpointable, 10-18 
checkpointing, 10-22, 10-28 
execution termination, 4-24 
extension size, 10-24 
file identification, 10-32 
fixed, 10-18 
initiation 
IOX 
EXECUTE command, 4-37 
install options, 10-29 
memory management support, 
10-18 
name 
CLI, 11-4 
reexecuting, 10-18 
removing, 10-18 
restrictions for fixing, 10-18 
size, 10-63 
system size, 10-18 
unfixing from memory, 10-92 
with external headers, 10-28 
with resident headers, 10-28 
Task Account Block, 17-3, 17-22 
Task accounting 
Resource Accounting, 17-6 
Task Control Block, 10-31 
/TASK keyword (VMR), 10-27 
Task-build file 
location of IOX, 4-22 
TASKLIST command (VMR), 10-88 
definition, 10-88 
examples, 10-88 to 10-89 
format, 10-88 
parameter, 10-88 


(VMR) 
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Telephone 
dial command string, 
TEMPORARYFILE command 
IOX, 4-63 
/TERM keyword (VMR), 10-78 to 
10-79 
Terminal 
baud rate, 
emulation, 
mute, 9-4 
nonslaved, 
port, 9-1 
Slaved, 10-50 
typeahead, 9-5 
Terminal emulation, 
establishing, 9-3 
terminating, 9-3 
Test configuration 
IOX 
pattern altering, 4-48 
pattern displaying, 4-48 
setup, 4-6 
TIM 
See TIME command 
Time 
displaying, 10-90 
setting, 10-90 
TIME command (VMR), 
definition, 10-90 
examples, 10-90 


9-4 


9-2 


9-1, 9-5 


10-50 


1-3 


(VMR) 


10-90 


Transaction file (Cont.) 
'- ° login data, 
offset definitions, 
print despooler block, 
print job data, 


17-2 

17-32 
17-36 
17-2 


set accounting block, 17-35 


size, 


17-5 


system account block (SAB), 


system data, 


17-35 
17-2 


system time change, 17-3 
system time change block, 17-36 


task data, 17-1 
user account block, 17-33 
user data, 17-1 

Transient failures, 15-31 


Translator processing, 12-19 

Transparent spooling, 7-1 

TST attribute, 12-39 

/TTSYNC keyword (VMR), 10-80 

Typeahead buffer, 9-5 

/TYPEAHEAD keyword (VMR), 
to 10-81 


10-80 


UAB 
Resource Accounting, 17-11 
UFD, B-1 
group number, B-1 
Accounting tasks, B-2 
DCL files, B-1l 


/TOP keyword (VMR), 


Transaction Account Block, 
Transaction file 


formats, 10-90 
notes, 10-91 
parameters, 10-90 

10-79 to 
10-80 


17-3 


account block linkages, 17-38 
account blocks, 17-11, 17-20 
system account block (SAB), 


17-11 
task account block (TAB), 
17-11 
transaction account blocks, 
17-11 
user account block (UAB), 
17-11 
accumulation fields, 17-33 


block diagrams, 17-22 
card reader job data, 17-3 
card reader spooling block, 
17-36 
crash recovery block, 
DATATRIEVE-11, 17-16 
device allocation, 
deallocation, or dismount 
data, 17-2 
device mount data, 17-2 
device statistics block, 
device usage data, 17-3 
disk accounting block, 17-36 
example, 17-12 
header area, 17-32 
invalid login block, 


17-35 


17-37 


17-36 


member number, 


UFD 
UFD 


Executive files, B-l 

FCP files, B-l 

FCS files, B-2 

K-Series files, B-2 

Line printer despooler, B-2 

MCR files, B-l 

On-line configuration, B-2 

Privileged utility tasks, B-1l 

Queue Manager files, B-2 

RMD files, B-l 

Shadow Recording, B-2 

SYSGEN Indirect command files, 
B-2 

B-2 

Object modules, B-2 

SLP correction files, B-2 

Source modules, B-2 

conventions, 1-6 

Group Number Identification 

Table, B-lt to B-2t 


UFD Member Number Identification 


UIC, 


authorized, 


Table, B-2t to B-3t 
10-25 
2-1 


contained in account entry, 2-1, 


displaying, 
distinction by password, 
/UIC keyword (VMR), 10-28, 


UNF 


2-7, 2-9 


2-5, 2-8 

2-1 
10-44, 
10-81 


See UNFIX command (VMR) 


UNFIX command 
definition, 
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(VMR), 
10-92 


10-92 


UNFIX command (VMR) (Cont.) 
example, 10-92 
format, 10-92 
keywords 
/REG, 10-92 
/RON, 10-92 
parameters, 10-92 
UNL 
See UNLOAD command (VMR) 
UNLINK command, 15-30 
UNLOAD command (VMR), 10-93 
definition, 10-93 
example, 10-93 
format, 10-93 
keyword 
/VEC, 10-93 
parameter, 10-93 
restrictions, 10-93 
User Account Block, 17-3, 17-23 
User File Directory 
See UFD 
User groups, 10-26 
User Identification Code 
See UIC 
User-controlled partition, 14-1 
User-written encryption routines 
support, 2-1 


VAX-1l RSX file transfer, 9-1, 
9-5 
VAX/VMS file transfer, 9-1, 9-5 
/VEC keyword (VMR), 10-34, 10-93 
VERIFY command 
IOX, 4-64 
effect on NFS volume, 4-8 
/VFILL keyword (VMR), 10-81 
Virtual Monitor Console Routine 
See VMR 
Virtual Monitor Console Routine 
(VMR) 
see VMR 
VMR, 1-3 
before starting, 10-1 
command abbreviations, 10-4 
command description format, 
10-7 
command descriptions, 10-7, 
10-93 
command format, 10-4 
command keyword values, 10-5 
command keywords, 10-4 
command names, 10-4 
command parameters, 10-4 
command syntax, 10-4 
command types, 10-1 
comments, 10-5 
definition, 10-1 
error messages, 10-94, 10-112 
exiting, 10-3 
file specifications 
components, 10-5 
default device, 10-5 
default directory, 10-6 
default file name, 10-6 


VMR 
file specifications (Cont.) 
default file types, 10-6 
default version number, 10-6 
device name, 10-5 
directory, 10-6 
file names, 10-6 
file type, 10-6 
format, 10-5 
/IM switch, 10-7 
specifying, 10-5 
version number, 10-6 
version number range, 10-6 
indirect command file, 10-3 
installing from LB:, 10-3 
introduction, 10-1 
prompt, 10-3 
relationship to MCR, 10-1 
running, 10-2 
starting, 10-1 to 10-2, 10-4 
system image file 
assigning SY: and LB:, 10-1 
bootstrap, 10-1 
relationship to symbol 
definition file, 10-1 
VMR commands 
ALTER, 10-8 
ASSIGN, 10-9 
CANCEL, 10-11 
CONFIGURATION, 10-12 
DEVICES, 10-16 
FIX, 10-18 
INSTALL, 10-21 
LOAD, 10-33 
LUNS, 10-35 
PARTITIONS, 10-36 
REASSIGN, 10-38 
REDIRECT, 10-39 
REMOVE, 10-40 
RUN, 10-42 
SAVE, 10-47 
SET, 10-50 
TASKLIST, 10-88 
TIME, 10-90 
UNFIX, 10-92 
UNLOAD, 10-93 
Volume 
Files-1l 


protecting with TEMPORARYFILE, 


4-63 
NES 
altering block range, 4-52 
displaying block range, 4-52 
error retries, 4-56 
list of parameter commands 
for, 4-9 
selecting 
with IOX, 4-58 
with VERIFY, 4-64 
selecting 
Files-ll for IOX, 4-8 
NFS for IOX, 4-8 
VOLUMECHECK command 
IOX, 4-65 
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WAIT command Write-check 


IOX, 4-66 enabling in IOX, 4-67 
/WB keyword (VMR), 10-28 WRITECHECK command 
/WCHK keyword (VMR), 10-81 IOX, 4-67 
/WRAP keyword (VMR), 10-82 to 
10--83 
Write-back cache data /XHR keyword (VMR), 10-28 
preventing loss, 5-5 XON/XOFF protocol, 9-2 
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